# WP5 — Assignment UI: who is responsible for what, and the switch that turns it on

**Repo:** FE (`/home/moonui2/public_html/moon-erp`) · **Branch:** `hazemdev2` · **Depends on WP4** · **BE change:** none (unless a lookup endpoint is missing — report, don't invent)

## Goal

Three surfaces:
1. **Assign** users to warehouses (and cash boxes) — nothing else in this feature works without it.
2. **Switch the mode** per company, per resource type.
3. **Review the migrated legacy data** before it becomes a live restriction.

## Where each belongs — follow the codebase, don't invent

The app already splits this three ways, and the analysis recommends keeping it:

| Thing | Surface | Existing precedent |
|---|---|---|
| **Membership** (which warehouses) | the **user edit dialog** | `branch_ids` is already a `p-multiselect` in `users.component.html` (~203-204), with assignments as chips in the users table and a branch filter over users |
| **Mode** (all / assigned / own_records) | **Settings** | the settings screen already renders module settings from definitions |
| **Roles' `data_scope`** | roles screen | already exists; untouched by this WP |

**Do not** put membership on the warehouse screen. It would be a second write path to the same pivot,
it has no precedent here, and — decisively — it makes the dependency below impossible.

## The dependency that decides the design

**The warehouse multiselect must offer only warehouses of the branches selected in the same dialog.**
A user assigned to Branch A should not be assignable to Branch B's warehouse. That is a live
dependency between two controls in one form — which the user-dialog pattern handles naturally and a
resource-screen pattern cannot express at all.

## The legacy review — read this before designing it

WP1 copied `warehouses.manager_id` and `petty_cash.custodian_id` into the new assignment tables **as a
starting point, not as an enforced restriction** (settled decision §9 Q7).

Those columns were settable from the UI for **months while filtering nothing**. Nobody ever validated
them, because nothing depended on them. Treating that data as a live restriction would lock people out
of their own warehouses the moment a company switches the mode on.

**So build a review surface:** show the migrated assignments, make them editable, and make it obvious
they are a *proposal*. The admin confirms before the mode is switched on. Design this as you judge
best — a filter on the users list, a dedicated review panel, or a banner on the settings screen when
migrated-but-unreviewed assignments exist. **Argue your choice in the report.**

## The mode switch needs a guard rail

Switching a company to `assigned` while users have **no assignments** produces empty screens for
everyone — because the engine correctly fails closed. That is right, and it is also a terrible first
experience.

**The settings screen must not let that happen silently.** At minimum: show how many users currently
have zero assignments for that resource before the switch takes effect. Whether you block, warn, or
merely inform is your call — argue it. What is not acceptable is flipping the switch with no signal.

## Acceptance criteria

1. A user's warehouses (and cash boxes) can be assigned and unassigned from the user dialog, saved
   through the existing save path, and shown as chips like `branch_ids` already is.
2. The warehouse options are constrained by the branches selected in the same dialog, live.
3. The mode setting is changeable from the settings screen, per resource type, bilingual.
4. Switching to a restrictive mode surfaces the count of users who would be locked out.
5. The migrated legacy assignments are visible and editable, and legible as a proposal.
6. `npx ng build --base-href /app/` green; `npx tsc --noEmit` no new errors.

## ⚠️ Note for whoever tests this

A newly granted permission — and by the same mechanism a newly changed assignment — **is invisible
until logout/login**, because the user and their permissions are cached in `localStorage['cached_user']`
at sign-in. Say so in the UI if you can do it cheaply; at minimum flag it in your report so the owner
isn't surprised during his pass.

## Environment / rules

- ⛔ **NEVER** `git checkout` / `restore` / `stash` on `src/assets/i18n/ar.json` or `en.json`.
  Additive edits only; any new key goes into BOTH files.
- Builds are pre-authorized. **Do NOT deploy to `/app`** — the orchestrator deploys.
- `chown moonui2:moonui2` every edited file. Commit on `hazemdev2`, conventional. **No push, no merge.**
- moonui2 ONLY — never `/home/moonui`. Never print a git remote URL.
- If a lookup endpoint you need does not exist, **report it — do not invent a backend change.**

## Out of scope

Backend changes · cash-box wiring (WP6) · cost centres / POS (WP7).