scalesApp/.claude/plans/reorder-nomenclatures-drag-drop.md

# Plan: Drag-to-reorder nomenclatures, reflected in vehicle "Additional Data"

## User Request

> in nomenclatures overlay, make the rows in the list draggable, so they can be rearranged. then in vehicle, show the fields in this order

Clarified with screenshots: the target is the **left-hand list in the Nomenclatures overlay**
(Агент, Товар, Товародател, № Контейнер, Корабособственик). The client wants to be able to move
e.g. "Агент" to the bottom of the list, and the vehicle screen's "Additional Data" dropdowns
should then appear in that same order.

## Plan

### Context

The backend already supports this fully: `Nomenclature.sort_order` exists
(`backend/nomenclatures/models.py:29`), `Meta.ordering = ["sort_order", "code"]`
(`models.py:32`), the viewset orders by it (`backend/api/views.py:260`), the serializer
exposes it as writable (`backend/api/serializers.py:264`), and `Main.jsx:31` already sorts
`vehicleNomenclatures` by it. **No backend change and no migration are needed.**

The reason the order looks fixed today is that every existing row has `sort_order = 0` — the
model default — so the sort is a no-op and rows fall back to `code` order. Assigning real
values on the first drag fixes that permanently.

Decisions taken with the user:
- Persist by PATCHing each moved row (frontend-only; no new endpoint).
- Save immediately on drop — no Save-button staging.
- The whole row is draggable (no separate grip handle).

### Scope

Two files change. Both are frontend.

#### 1. `frontend/src/components/NomenclatureManager/NomenclatureManager.jsx`

Add native HTML5 drag-and-drop to the left list (lines 189–217). No library — `package.json`
has no DnD dependency and adding one for a five-row list is not warranted.

**State:** two new pieces of local state — `dragIndex` (index of the row being dragged,
`null` when idle) and `dragOverIndex` (index the row would drop into, for the drop-line
indicator). Plus reuse of the existing `error` state for failure messages.

**Row markup** (`.nm-list-item`, line 191): add
- `draggable={canEdit}` — reordering is an edit, so gate it on the same `canEdit`
  (`currentUser?.can_manage_entities`) that already gates the edit/add/delete buttons.
- `onDragStart` → record `dragIndex`; call `e.dataTransfer.setData('text/plain', String(idx))`
  (Firefox refuses to start a drag without data set) and `e.dataTransfer.effectAllowed = 'move'`.
- `onDragOver` → `e.preventDefault()` (required or no drop event fires) and set `dragOverIndex`.
- `onDragEnd` → clear both indices (fires even on a cancelled drag, so it is the reliable reset).
- `onDrop` → `e.preventDefault()`, then run the reorder below.
- `className` gains conditional `nm-list-item--dragging` / `nm-list-item--drag-over` modifiers.

Change the `.map(nom => ...)` at line 190 to `.map((nom, idx) => ...)` so handlers have the
index. The React `key={nom.id}` at line 192 is already stable and correct — leave it.

**Reorder handler** `handleDrop(targetIdx)`:
1. Bail if `dragIndex === null || dragIndex === targetIdx`.
2. Build the reordered array with a splice-out/splice-in on a copy of `nomenclatures`.
3. Write `sort_order: i` onto every element of the new array, and `setNomenclatures(...)`
   immediately — optimistic update, so the list does not visibly snap back while the requests
   are in flight.
4. Diff against the previous array and PATCH only rows whose `sort_order` actually changed:
   `api.patch('/api/nomenclatures/${id}/', { sort_order: i })`, all in one `Promise.all`.
   PATCH (not PUT) matters — `NomenclatureSerializer.update` deletes and recreates the whole
   `fields` collection (`backend/api/serializers.py:284-287`), so a PUT without a `fields` key
   would wipe the field definitions. A partial update leaves `fields` untouched.
5. On rejection: `setError('Failed to save order')` and `await loadNomenclatures()` to resync
   from the server.

Note the first drag will PATCH nearly every row, because they all currently sit at
`sort_order = 0` and the diff sees every position as changed. That is correct and self-healing —
subsequent drags only touch the rows between the source and target.

**One caveat to handle:** each PATCH triggers `sse_broadcast_update('nomenclature', 'update', ...)`
(`backend/api/views.py:268`), and `NomenclatureDataContext.jsx:82-85` responds to any
`nomenclature` event with a full `loadAll()` refetch. For a 5-row reorder that is ~5 events
collapsing into a few refetches of a small payload — acceptable, and it is what makes the
vehicle screen update live without a page reload. No debounce needed at this scale; revisit
only if the list ever grows large.

#### 2. `frontend/src/components/NomenclatureManager/NomenclatureManager.css`

- `.nm-list-item` (line 117) — the existing rule already has `cursor: pointer`; leave it. Add
  `user-select: none` so dragging does not paint a text selection across the row.
- `.nm-list-item--dragging` — `opacity: 0.4`, to show which row is in flight.
- `.nm-list-item--drag-over` — a drop indicator in the accent already used by
  `.nm-list-item--active` (line 132). Because `.nm-list-item` has a `border-bottom` (line 122),
  use an inset `box-shadow: inset 0 2px 0 #667eea` rather than a border so row height does not
  shift by 2px during the drag.

### Explicitly not in scope

- `NomenclatureField` rows (the "Fields" table on the right panel) — they have their own
  `sort_order` that the save payload currently drops, but the user asked about the left list
  only. Flagged to the user as a separate known gap, not fixed here.
- `NomenclatureEntry` ordering — entries have no `sort_order` column at all; that would need a
  migration. Not requested.
- `Main.jsx` — **no change required.** Line 31 already sorts by `sort_order`. Left as is.

### Verification

1. Start backend (`cd backend && uvicorn scalesapp.asgi:application --reload`) and frontend
   (`cd frontend && npm start`); log in as a user with `can_manage_entities`.
2. Open the Nomenclatures overlay. Drag **Агент** from the top to the bottom of the left list.
   Verify: the row follows the cursor with a drop indicator, and lands last on release.
3. Check the Network tab: several `PATCH /api/nomenclatures/{id}/` requests, each with a
   `{sort_order: N}` body only, all returning 200.
4. Without reloading, look at the vehicle screen's "Additional Data" section — **АГЕНТ should
   now be the last dropdown**, moved there live by the SSE-driven `loadAll()`.
5. Hard-reload the page (F5) and confirm both the overlay list and Additional Data still show
   Агент last — this proves it persisted rather than only living in local state.
6. Re-open the overlay, click a nomenclature to edit it, and confirm its **Fields table still
   lists its fields** — this is the PUT-vs-PATCH regression guard from step 4 of the handler.
7. Log in as a user without `can_manage_entities` and confirm rows are not draggable.