Law/context/03_admin_panel_service.md

# Admin Panel Service Context

## Roles
- ADMIN: full CRUD + all dictionaries + SLA + users + quotes
- LAWYER:
  - see assigned requests
  - see unassigned queue
  - can manually claim unassigned request ("Take in work")

## Core Features
- Universal table with filters (`= != > < >= <= ~`)
- Universal record modal (meta-driven)
- Manual editing of available entities
- AuditLog for any CREATE/UPDATE/DELETE and system assignment events
- Atomic claim action to prevent race conditions between lawyers
- User profile avatar (`avatar_url`) with fallback initials in UI
- Lawyer profile includes default lawyer rate (editable by ADMIN)
- Lawyer profile includes salary percent (editable by ADMIN)

## Assignment Logic
- Request can be claimed manually by lawyer
- Manual claim is allowed only when `assigned_lawyer_id` is null
- Lawyer takeover is forbidden
- Manual reassignment of assigned request is ADMIN-only action
- If not claimed within 24h and still unassigned, auto-assign is applied
- Lawyer profile includes:
  - one primary topic
  - additional topics
- Additional topics are stored via separate link table (`admin_user_topics`)
- Assignment priority: primary topic matches first, then additional topics, then lowest active load
- Active load = count of assigned requests with non-terminal status (`is_terminal=false`)

## Status Logic
- Status flow is configured per topic
- Base model is linear, but with allowed flow variations (Jira-like)
- On any status change:
  - all previous messages immutable
  - all previous attachments immutable
  - add `status_history` record

### Implemented Flow Configuration (`P14`)
- New dictionary table: `topic_status_transitions`
- Transition rule fields:
  - `topic_code`
  - `from_status`
  - `to_status`
  - `sla_hours` (SLA для перехода, в часах)
  - `enabled`
  - `sort_order`
- ADMIN manages flow rules in "Справочники -> Переходы статусов"
- Server-side validation:
  - if topic has configured enabled rules, transition is allowed only when rule exists
  - if topic has no rules yet, backward-compatible free transition is kept

### Planned Billing Status Extension
- Add status type: `INVOICE` / "Выставление счета"
- For this status type:
- invoice is generated from admin-managed template
- invoice is attached/sent to client through platform notification channel
- billing status can be included in topic-specific flow as regular transition node

### Implemented Billing Status Flow (`P25`)
- `statuses.kind` supports:
- `DEFAULT` (regular status)
- `INVOICE` (billing step: выставление счета)
- `PAID` (business payment fact status)
- `statuses.invoice_template` stores admin-managed invoice template with placeholders (`{track_number}`, `{client_name}`, `{topic_code}`, `{amount}` and others).
- On request status transition to `INVOICE` kind:
- system auto-creates waiting invoice (`WAITING_PAYMENT`) from template
- invoice is linked to request and available in ADMIN/LAWYER + public cabinet
- On request status transition to `PAID` kind:
- only ADMIN can perform this transition
- latest waiting invoice is marked as paid
- request payment fields are fixed (`invoice_amount`, `paid_at`, `paid_by_admin_id`)
- Multiple billing cycles in the same request are supported (sequential invoice->paid events).

### Implemented SLA Transition Config (`P18`)
- SLA configuration is stored in `topic_status_transitions.sla_hours`
- `sla_hours` is optional but if set must be integer > 0
- CRUD validation prevents:
- unknown `topic_code` / status codes
- `from_status == to_status`
- non-positive `sla_hours`
- Admin UI for "Переходы статусов" includes `SLA (часы)` in table, filters, and edit/create modal

### Implemented Status Immutability (`P15`)
- On request status change:
  - all existing `messages` for request are marked `immutable=true`
  - all existing `attachments` for request are marked `immutable=true`
  - new row is written into `status_history` (`from_status`, `to_status`, `changed_by_admin_id`)
- Immutable records protection:
  - `PATCH /api/admin/crud/messages/{id}` and `DELETE /api/admin/crud/messages/{id}` are blocked for immutable rows
  - `PATCH /api/admin/crud/attachments/{id}` and `DELETE /api/admin/crud/attachments/{id}` are blocked for immutable rows
  - upload complete rejects binding file to immutable message (`message_id`)

## Templates
- ADMIN configures required client fields for request creation (by topic)
- For in-progress work, lawyer can use topic template for requested docs/data
- Lawyer can extend that template for a specific request only
- No template versioning requirement

### Implemented Template Split (`P16`)
- New dictionaries:
- `topic_required_fields`: required request creation fields per topic (`topic_code`, `field_key`, `required`, `enabled`, `sort_order`)
- `topic_data_templates`: topic-level data/doc request template (`topic_code`, `key`, `label`, `description`, `required`, `enabled`, `sort_order`)
- Request-level table:
- `request_data_requirements`: per-request expanded template items, including lawyer-added custom items
- Validation:
- create request (`/api/public/requests`, `/api/admin/requests`, `/api/admin/crud/requests`) validates `extra_fields` against active required keys from `topic_required_fields`
- Request template API:
- `GET /api/admin/requests/{request_id}/data-template`
- `POST /api/admin/requests/{request_id}/data-template/sync`
- `POST /api/admin/requests/{request_id}/data-template/items`
- `PATCH /api/admin/requests/{request_id}/data-template/items/{item_id}`
- `DELETE /api/admin/requests/{request_id}/data-template/items/{item_id}`
- RBAC:
- ADMIN has full access
- LAWYER can work with template items only for assigned request

## Rates & Billing Rules (planned)
- ADMIN sets default lawyer rate in user profile
- ADMIN sets lawyer salary percent in user profile
- ADMIN can override rate for a specific request
- Effective request rate is stored in request and frozen for financial traceability
- Request rate is not returned in public client endpoints and not shown in public UI
- Effective request amount is stored in request and frozen for financial traceability
- Fact of payment is recorded when ADMIN changes request status to "Оплачено" (business paid event)
- Payment event stores who changed status and when (for salary/month reports)
- A request may contain more than one payment event (multiple invoice-payment cycles)

### Implemented Rate Rules (`P24`)
- On first assignment (`claim`, `reassign`, `auto-assign`, create/update request with assigned lawyer), `requests.effective_rate` is auto-filled from `admin_users.default_rate` if request rate is empty.
- If request already has `effective_rate`, assignment/reassignment does not overwrite it.
- LAWYER role cannot create/update request financial fields (`effective_rate`, `invoice_amount`, `paid_at`, `paid_by_admin_id`).
- Public client API does not expose internal request financial fields.

### Implemented Baseline For Dashboard (`P21`)
- Financial profile fields are persisted:
- `admin_users.default_rate`
- `admin_users.salary_percent`
- Request financial fields are persisted:
- `requests.effective_rate`
- `requests.invoice_amount`
- `requests.paid_at`
- `requests.paid_by_admin_id`
- Admin UI record forms/tables include these fields.
- Public API still does not expose internal financial fields.

## Read / Unread UX
- Unread state is tracked per request for both LAWYER and PUBLIC user
- New message/file/status change marks request as updated
- Opening request marks updates as read
- UI can show one-time green indicator for what changed (message/file/status)

## Implemented Marker Model (`P13`)
- `requests.client_has_unread_updates` / `requests.client_unread_event_type`
- `requests.lawyer_has_unread_updates` / `requests.lawyer_unread_event_type`
- Event types: `MESSAGE`, `ATTACHMENT`, `STATUS`
- LAWYER opening request (`GET /api/admin/crud/requests/{id}` or `GET /api/admin/requests/{id}`) clears lawyer marker
- Client opening request (`GET /api/public/requests/{track_number}`) clears client marker

## Admin Dashboard Financial Metrics (planned)
- For each lawyer show:
- active requests count (current load)
- sum of active requests amounts (if amount exists)
- monthly gross of paid requests
- monthly gross of paid events
- monthly salary amount
- Salary calculation base:
- paid event = ADMIN changes request status to "Оплачено"
- salary = paid request amount * lawyer salary percent

## Implemented File Security Audit (`P26`)
- Added dedicated immutable security log table: `security_audit_log`.
- File operations in admin/public upload APIs now produce security events:
- `UPLOAD_INIT`, `UPLOAD_COMPLETE`, `DOWNLOAD_OBJECT`.
- Both successful and denied attempts are logged (including RBAC denials on download).
- `security_audit_log` is exposed in admin dictionaries as read-only (query/read only, no update/delete via universal CRUD).