TASKS-1823 WebManager module

2026-08-28 08:35:58 +00:00
parent fdb2cf3837
commit c93d8c025b
654 changed files with 26232 additions and 6075 deletions
@@ -0,0 +1,69 @@
+# Module Generator Frontend
+
+The generator UI collects module metadata, selected assets, form layout, and datatable configuration, converts it into TypeScript/TSX source strings, and sends them to the backend generator.
+
+| Responsibility                                         | Source (under `apps/admin/src/devtools/`)                     |
+| ------------------------------------------------------ | ------------------------------------------------------------- |
+| Page submission, notifications, and mutation callbacks | `pages/ModuleGeneratorPage/index.tsx`                         |
+| Payload assembly                                       | `pages/ModuleGeneratorPage/lib/buildGenerateModulePayload.ts` |
+| Form state, initial values, and sections               | `view/forms/ModuleGeneratorForm/`                             |
+| Payload DTOs and HTTP client                           | `data/api/`                                                   |
+| React Query hooks                                      | `data/queries/`                                               |
+| Source-code builders                                   | `data/builders/`                                              |
+
+The page submits through `useGenerateModule`; success resets the form and shows an alert, errors go through the shared React Query error helpers.
+
+## Metadata and Assets
+
+Required metadata: `name` (frontend folder, backend module identity, route segment, permission-slug base), `table` (existing PostgreSQL table), `generate` (selected assets). Backend assets are all selected by default; form and datatable are opt-in.
+
+| Asset        | Workspace | Output                                              |
+| ------------ | --------- | --------------------------------------------------- |
+| `model`      | Backend   | Lucid model                                         |
+| `controller` | Backend   | Authenticated resource controller and test          |
+| `routes`     | Backend   | Resource route registration                         |
+| `validator`  | Backend   | Create and update Vine validators                   |
+| `policy`     | Backend   | Bouncer policy and permission configuration         |
+| `api`        | Backend   | API controller, validators, routes, and test        |
+| `form`       | Frontend  | Form definition, component, and modal/sheet trigger |
+| `datatable`  | Frontend  | List page table and menu entry                      |
+
+Before generation the UI reads `GET /makeModule/tables` (table selector) and `GET /makeModule/columns/:table` (field choices) — cached via React Query, columns disabled until a table is selected.
+
+## Payload Builders
+
+`buildGenerateModulePayload` delegates to focused builders:
+
+| Builder                             | Payload field    | Generated destination               |
+| ----------------------------------- | ---------------- | ----------------------------------- |
+| `FormSourceBuilder.buildComponent`  | `form`           | `view/forms/MainForm/Component.tsx` |
+| `FormSourceBuilder.buildDefinition` | `formDefinition` | `view/forms/MainForm/form.ts`       |
+| `ManageTriggerSourceBuilder`        | `formDialog`     | `view/widgets/ManageTrigger.tsx`    |
+| `DataTableSourceBuilder`            | `dataTable`      | `view/widgets/DataTable.tsx`        |
+| `ListPageSourceBuilder`             | `list`           | `pages/ListPage/index.tsx`          |
+| `MenuSourceBuilder`                 | `menu`           | `config/menu.ts`                    |
+| `ModuleConfigSourceBuilder`         | `module`         | `config/module.ts`                  |
+
+Form disabled → `form`, `formDefinition`, `formDialog` are `null`. Datatable disabled → `dataTable` and `menu` are `null`, and the list-page builder emits a page without a table.
+
+## Generated Frontend Architecture
+
+```txt
+apps/admin/src/modules/<name>/
+├── api/           # create.ts, delete.ts, detailed.ts, keys.ts, list.ts, update.ts
+├── config/        # translation/, menu.ts, messages.ts, meta.ts, module.ts, routing.tsx
+├── entities/      # Entity.ts (from database columns)
+├── pages/ListPage/
+└── view/
+    ├── forms/MainForm/    # Component.tsx, constants.ts, form.ts, index.ts, submit.ts
+    ├── layouts/Layout.tsx
+    └── widgets/           # DataTable.tsx, DeleteTrigger.tsx, ManageTrigger.tsx
+```
+
+`api/` deliberately has no barrel file — each CRUD operation is its own file, imported directly (`import { useCreate } from "../../../api/create"`); `keys.ts` owns query key builders, `list.ts`/`detailed.ts` their invalidation helpers.
+
+Layer ownership: `entities/Entity.ts` is shared by API hooks, forms, and widgets; `api/` owns Axios calls, hooks, keys, and notifications; `pages/` owns route composition and permission gates; `view/forms/` owns schema, values, UI, and submission; `view/widgets/` owns stateful interactions; `config/` integrates routes, menu, translations, and permissions with the module registry.
+
+## Extending
+
+To add a generated frontend artifact: add its configuration type under `entities/`, UI controls to `ModuleGeneratorForm`, a focused builder under `data/builders/` (for dynamic source), the payload field to `GenerateModulePayload` + `buildGenerateModulePayload`, accept and write it in `module_controller.ts`, and add static structure to `_template/` when every module needs it. Verify generation with and without the asset selected.