descrybe/docs/admin-roles-support/10-admin-orgs-ui.md

# 10 — Admin users & organizations UI (agent 10/20)

**Owns:** `/admin/users` — users directory, company list with plan view/assign, platform staff role assignment.  
**Does not own:** Billing plans table (agent 9), Permissions panel (agent 8), staff middleware/model (agent 6), admin shell chrome (agent 7 — nav label only).  
**Gate:** `requirePlatformAdmin` (full admin / developer). `support_staff` is excluded.

---

## PROBLEM

`/admin/users` was a thin client-filtered user list (no companies, no plan view, no staff role edits, no server pagination). Operators needed one place to manage orgs and staff after cutover.

---

## Delivered

1. **Users tab** — server-paginated (`limit`/`offset`, page size 25), search (`q`), staff-only filter, set-password invite + local dev tools preserved.
2. **Staff roles** — dialog → `PATCH /api/admin/users/{id}/staff-role` with `admin` | `developer` | `support_staff` | clear. Uses agent 6 API; self-change blocked server-side.
3. **Companies tab** — paginated list with active plan name, legacy/public/custom badge, credits remaining/total, “without plan” filter.
4. **Assign plan** — dialog lists all admin plans (ladder + legacy + custom) → `POST /api/admin/plans/assign`.
5. **API enrichments** — `GET /api/admin/users` returns `total`, `staff_role`, `resolved_role`, search/filters; `GET /api/admin/companies` returns `total`, `plan_id` / `plan_name` / `plan_is_*`, search.
6. **Fix A1 catalog** — Companies tab button + confirm → `POST /api/admin/companies/{id}/fix-catalog` (prompt repair + hygiene; flash counts `prompts`/`hashes`/`categories`).
7. **Clone catalog** — existing sandbox clone flow (separate from Fix A1).

---

## Source files

| File | Intent |
|------|--------|
| `apps/web/src/routes/admin/users/+page.svelte` | Orgs UI (users + companies tabs) |
| `apps/web/src/lib/admin-orgs.ts` | Client helpers + types |
| `apps/api/internal/httpapi/admin_orgs_handlers.go` | Paginated list handlers |
| `apps/api/internal/httpapi/admin_staff_handlers.go` | Staff role PATCH (agent 6) |
| `apps/web/src/lib/components/AdminNav.svelte` | Nav label “Users & orgs” |

---

## API contract

| Method | Path | Use |
|--------|------|-----|
| `GET` | `/api/admin/users?limit&offset&q&staff_only&active_only&inactive_only` | User directory |
| `PATCH` | `/api/admin/users/{id}/staff-role` | Body `{ "staff_role": "admin"\|"developer"\|"support_staff"\|null }` |
| `GET` | `/api/admin/companies?limit&offset&q&without_active_plan` | Companies + plan summary |
| `GET` | `/api/admin/plans` | Plan picker |
| `POST` | `/api/admin/plans/assign` | `{ company_id, plan_id }` |
| `POST` | `/api/admin/emails/set-password` | Existing invite tooling |
| `POST` | `/api/admin/companies/{id}/fix-catalog` | In-place Fix A1 / catalog hygiene (`confirm=true`) |
| `POST` | `/api/admin/companies/{id}/clone-catalog` | Clone source catalog into admin sandbox |

All under `RequireSession` + `RequirePlatformAdmin` (full admin only).

---

## Fix A1 catalog (`POST …/fix-catalog`)

In-place hygiene for one company (prefer **Platform Demo**; A1 allowed with confirm). Never clears catalog, never mass-reprocesses, never uses A1 as a clone destination.

**Body:** `{ "confirm": true, "backfill_categories"?: true, "reprocess_sample_limit"?: 25 }`

**Sequence** (`processing.FixCompanyCatalog`):

1. Ensure `category_attributes` links (orphan purge only)
2. `RepairCompanyCategoryEnhancePrompts` — same map as `RepairA1DemoCategoryEnhancePrompts` / `go run ./cmd/repair-category-prompts -apply`
3. Re-apply BuiltIn `product_enhance` templates (when AI prompts service is wired)
4. `FixCatalogHygieneWithIDs` — weak enhance hashes, optional category backfill, description/meta hygiene
5. Sanitize `processed_attributes`
6. Return recommended reprocess `raw_product_id` sample (no auto reprocess)

**Flash success** (`flash.admin.fixA1Success` — keys `admin.users.fixA1*`):

| Flash param | `result` field | Also as |
|-------------|----------------|---------|
| `{prompts}` | `prompts` | `category_prompts_updated` |
| `{hashes}` | `hashes` | `weak_hashes_cleared` |
| `{categories}` | `categories` | `categories_backfilled` |
| `{name}` | company name from UI row | `company_name` |

UI: Companies tab wrench → confirm dialog → `fixAdminCompanyCatalog` in `$lib/admin-orgs.ts`.

---

## Security / performance

- AuthZ enforced server-side; UI gate is UX only.
- Cannot change own staff role (agent 6 handler).
- Lists use SQL `LIMIT`/`OFFSET` + `COUNT(*)` — no full-table client filter.
- Company plan join is a single query (no N+1).

**ASSUMPTION:** `users.staff_role` migration (`029_staff_roles.sql`) applied. UI shows an info banner if PATCH returns 404/501.

---

## Manual verify

1. Platform admin → `/admin/users`.
2. Search users; toggle Staff only; page Next/Previous.
3. Assign staff role (admin / developer / support_staff); confirm badge.
4. Companies tab → see plan badge; filter Without plan; Assign plan (legacy + public).
5. Companies tab → Fix A1 catalog on Platform Demo (or A1 with confirm); success flash shows prompts/hashes/categories counts.
6. As `support_staff`, confirm `/admin/users` is forbidden (full-admin-only nav).

---

## Coordination

- Agent 6: staff model + `PATCH …/staff-role` + `RequirePlatformAdmin` excluding support_staff.
- Agent 9: billing assign UX remains; orgs page is the directory-focused assign path.
- Agent 14: support_staff queue access after role grant from this UI.