# WP1 — Permission Catalog (BE) + enrich `GET /core/permissions`

## Goal
Give every permission a human meaning the roles screen can display: a **PHP `PermissionCatalog`** class (generalizing `Modules/LIS/app/Support/LisScreenCatalog.php`) that maps permission keys → `label_ar/label_en`, `desc_ar/desc_en`, `danger` (bool), `kind` (`primary|action|required`), and a `resource`/`screen` grouping. Then enrich the `GET /core/permissions` response so each permission key carries this metadata (merged onto the existing shape). Cover **Accounting, Sales, Purchases, Core** first; every other permission must degrade gracefully (no catalog row → endpoint still returns the key with `label`, and the FE composes its old label). **No DB migration** — a PHP catalog like LisScreenCatalog (lower risk on `moonui2_dev_be`, CI-testable).

## Exact files
- **Create:** `/home/moonui2/moon-erp-be/Modules/Core/app/Support/PermissionCatalog.php` — the catalog class. Mirror `LisScreenCatalog`'s style. Suggested API:
  - `PermissionCatalog::all(): array` — keyed by permission string → `['label_ar','label_en','desc_ar','desc_en','danger','kind','module','resource','screen']`.
  - `PermissionCatalog::for(string $perm): ?array` — one lookup (null if absent).
  - Internally organize by module → resource → actions so it's easy to extend and so a matrix/by-screen view can be derived. Include a `resource` label (`ROLES.RESOURCES`-equivalent Arabic) and a `screen`/route hint (where the permission is used) per resource.
- **Modify:** `/home/moonui2/moon-erp-be/Modules/Core/app/Http/Controllers/RoleController.php` — method `permissions()` (line ~191). Keep the existing `groupBy(module)` shape and the `{key,label}` pairs (do NOT break current FE), but ADD per-permission fields from the catalog: `label_ar, label_en, desc_ar, desc_en, danger, kind, resource`. When no catalog row exists, keep `label => $p` and omit/blank the description fields (FE falls back).
- **Create test:** `/home/moonui2/moon-erp-be/Modules/Core/tests/Feature/PermissionCatalogTest.php` — (a) every catalog key is a REAL permission in `RolePermissionSeeder::permissions()` (no typos / stale keys); (b) `GET /core/permissions` returns catalog metadata for a sampled Sales/Purchases/Accounting/Core permission; (c) a permission with NO catalog row still appears with its key + composed label (fallback path).

## Reference (read these — do not re-derive)
- Pattern to generalize: `Modules/LIS/app/Support/LisScreenCatalog.php` (item shape: `['perm','kind','label_ar','label_en','desc_ar','desc_en','danger'=>true]`) and its CI gate `Modules/LIS/tests/**/LisScreenCatalog*Test.php`.
- Catalog source of truth for real keys: `Modules/Core/database/seeders/RolePermissionSeeder.php` (`permissions()` 293–1480).
- Current endpoint shape (must stay backward-compatible): `RoleController@permissions` returns `{ data: { <module>: [ {key,label}, ... ] } }`.

## Interfaces (later WPs depend on this)
- **Exposes to WP3 (FE roles screen):** `GET /core/permissions` → `{ data: { <module>: [ { key, label, label_ar?, label_en?, desc_ar?, desc_en?, danger?, kind?, resource? }, ... ] } }`. Fields beyond `key,label` are OPTIONAL per row. WP3 renders `desc_*` as the info tooltip, `danger` as the red styling, `resource` to group the matrix rows; falls back to the composed `resource - action` label when they are absent.
- **Convention for WP4/future:** the catalog `resource`/`screen` field is the canonical "where is this permission used" note.

## Acceptance criteria
- [ ] `PermissionCatalog.php` exists; covers Accounting + Sales + Purchases + Core resources with `label_ar/en` + `desc_ar/en` + `danger` on delete/post/approve/convert actions.
- [ ] Every catalog key exists in `RolePermissionSeeder::permissions()` (proven by the new test).
- [ ] `GET /core/permissions` returns the enriched fields for covered permissions AND still returns `{key,label}` for uncovered ones (no regression to the current FE contract).
- [ ] `PermissionCatalogTest` green.

## Tests
- New `PermissionCatalogTest` (above). Also re-run `RoleApiTest`, `SetupPermissionTest`, `AdditiveRolePermissionsTest`, `Wp8aActionPermissionsTest` — must stay at baseline (no NEW failures).

## Flags
- **[FIN]** — touches the permission surface that gates financial documents (Accounting/Sales/Purchases). Fable/advisor consult required on the catalog's danger/kind classification for money actions (post/approve/convert).
- **Migration:** NO (PHP catalog).

## Out of scope
- Do NOT change `RolePermissionSeeder` permission strings. Do NOT touch the FE. Do NOT add descriptions for LIS/HR/etc. beyond the four priority modules (incremental — later).
- Do NOT change `permissionMatches`/`*appCan`/guards (that's WP4).