---
module: claims.claim-detail
title: Claim Detail
tab: Claude
order: 40
audience: dev
---

Terse agent reference for the **Claim Detail** panel (`ClaimPanel.svelte`).

## Ownership
- **Service:** `hiveops-claims` OWNS all of this — claims, payments, messages, notes, attachments. No other service serves panel data.
- **Backend:** `hiveiq-claims`, port 8092, base path `/api/claims`.
- **External route:** `api.bcos.cloud/claims/` → `hiveiq-claims:8092/api/claims/`.
- **Frontend:** `hiveiq-claims-frontend`, `claims.bcos.cloud`, port 5179, component `ClaimPanel.svelte`.
- **DB:** `hiveiq_claims` (Postgres prod on `10.10.10.188`; H2 in `dev`).

## Endpoints (METHOD path) — all require JWT; `{uuid}`/`{claimUuid}` = claim UUID

| Method | Path | Use |
|--------|------|-----|
| GET | `/api/claims/{uuid}` | Load claim + embedded `payments` |
| PUT | `/api/claims/{uuid}` | Body `{status,claimType,citVendorUuid\|clearCitVendor,spVendorUuid\|clearSpVendor}` |
| GET | `/api/claims/vendors` | Edit + message dropdowns (`?type=CIT\|SP`) |
| GET | `/api/claims/{claimUuid}/messages` | `?vendorUuid=` optional filter |
| POST | `/api/claims/{claimUuid}/messages` | `{messageText,vendorUuid?,additionalEmail?}` → sends SMTP email |
| GET | `/api/claims/{claimUuid}/notes` | internal notes |
| POST | `/api/claims/{claimUuid}/notes` | `{noteText}` |
| GET | `/api/claims/{claimUuid}/attachments` | list |
| POST | `/api/claims/{claimUuid}/attachments` | multipart field `file` → sends SMTP email |
| GET | `/api/claims/{claimUuid}/attachments/{attachmentUuid}/download` | stream file |
| GET | `/api/claims/{claimUuid}/payments` | (panel uses embedded instead) |
| PUT | `/api/claims/{claimUuid}/payments/{party}` | `party`∈`INSTITUTION\|CIT\|SP`; body `{amountOwed,amountPaid}` |

## Tables (`hiveiq_claims`)
- `claims`, `claim_payments`, `claim_messages`, `claim_notes`, `claim_attachments`, `vendors`, `email_templates`, `device_summary`.

## Kafka
- **Consume:** `hiveops.device.events` (group `hiveops-claims-device-sync`) → `device_summary`.
- **Produce:** none. Claim/payment changes emit no events.

## Enums
- `ClaimStatus`: `OPEN`, `WAITING_CIT`, `WAITING_SP`, `WAITING_INSTITUTION`, `PENDING_PAYMENT`, `RESOLVED_PAID`, `RESOLVED_OFFAGE_FOUND`, `RESOLVED_DENIED`.
- `ClaimType`: `WITHDRAW`, `DEPOSIT`. Payment `Party`: `INSTITUTION`, `CIT`, `SP`.

## Roles
- **None.** `SecurityConfig` = `anyRequest().authenticated()`. No `hasAnyRole`. Isolation = `institutionKey` from JWT (`ClaimsPrincipal`), enforced in service layer for LIST only.

## Gotchas
- `GET/PUT /api/claims/{uuid}` and every `/{claimUuid}/…` activity endpoint resolve by UUID with **no `institutionKey` check** → cross-institution read/write (IDOR). Only `GET /api/claims` (list) is scoped.
- Panel `PUT` sends `clearCitVendor/clearSpVendor=true` when a vendor select is blank → saving Edit can delete a vendor + its payment row.
- Assigning a vendor later adds its `claim_payments` row at `amountOwed=0` — no re-split.
- Message/attachment emails go via **SMTP (`JavaMailSender`)**, not Kafka; silently skipped if no recipient resolves or SMTP unconfigured (record still saves).
- Message/notes/attachments tabs swallow load errors (empty `catch {}`) — no toast; check logs.
- Attachments stored on local disk `UPLOADS_DIR` (default `/tmp/claims-uploads`); lost if not a volume. Cap 50MB/file, 52MB/request.
- List filter params are `status`,`claimNumber`,`terminalId` (NOT `search`).
- `dev` = H2 create-drop, Flyway off; `prod` = Postgres validate.

## Do NOT
- Do NOT assume role gates exist — there are none; do not tell users an action is "admin-only."
- Do NOT expose claim UUIDs as safe identifiers — they bypass institution scoping.
- Do NOT expect a Kafka event after a claim/payment change — none is produced.
- Do NOT look in incident/mgmt/devices for claim data — it's all in `hiveops-claims`.
- Do NOT trust `device_summary` freshness — no reconciler; verify against the devices service.
- Do NOT call `/api/internal/**` for panel work — it's email-template only, `X-Internal-Secret`-gated.

See [claims.claim-detail] Internal + Architect tabs. [platform.service-ownership] · [platform.kafka] · [platform.data-architecture]
