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,53 @@
+# Module Generator
+
+Creates a backend module and a matching admin frontend module from an existing PostgreSQL table, combining database metadata with frontend code builders and Handlebars templates. The output is a maintainable starting point — generated authorization, validation, relationships, API behavior, labels, and translations must still be reviewed for the product domain.
+
+| Part                            | Source                                              |
+| ------------------------------- | --------------------------------------------------- |
+| Generator page and form         | `apps/admin/src/devtools/`                          |
+| Copied frontend module template | `apps/admin/src/modules/_template/`                 |
+| Generator HTTP endpoints        | `apps/backend/start/routes.ts`                      |
+| Generator controller            | `apps/backend/app/controllers/module_controller.ts` |
+| Database inspection             | `apps/backend/app/services/database_inspector.ts`   |
+| Backend Handlebars templates    | `apps/backend/app/templates/backend/`               |
+| Frontend Handlebars templates   | `apps/backend/app/templates/frontend/`              |
+
+Details: [frontend.md](./frontend.md) (UI, payload builders, generated frontend), [backend.md](./backend.md) (endpoints, inspection, templates, generated backend), [troubleshooting.md](./troubleshooting.md) (module not loaded / missing from menu).
+
+## Prerequisites
+
+1. Backend running from `apps/backend/` (destinations resolve relative to `process.cwd()`); admin app in dev mode; authenticated session (all endpoints use auth middleware).
+2. The source table created and migrated — the form reads PostgreSQL `information_schema`.
+3. A module name valid as a TypeScript identifier, route segment, permission slug, and folder name.
+
+## Generation Flow
+
+```mermaid
+flowchart LR
+  A["Select table and assets"] --> B["Configure form and table"]
+  B --> C["Frontend builders create source strings"]
+  C --> D["POST /makeModule/generate"]
+  D --> E["Inspect database metadata"]
+  E --> F["Copy frontend _template"]
+  E --> G["Render backend templates"]
+  F --> H["Write configured frontend files"]
+  G --> I["Write backend module and tests"]
+```
+
+Output goes to `apps/backend/modules/<ModuleName>/`, `apps/backend/tests/modules/<ModuleName>/`, and `apps/admin/src/modules/<name>/`. Frontend modules are discovered through their `config/module.ts` manifest; backend routes load from `apps/backend/modules/` at startup.
+
+## Operational Behavior
+
+- Generation writes directly into both workspaces — no preview, transaction, or rollback; existing files may be overwritten. Generate into a clean name and inspect the Git diff.
+- Select `model` whenever you select `api` — API generation imports the model for its Swagger schema.
+- The frontend template is always copied; form and datatable files are populated only when selected.
+- Generated code is not formatted or committed automatically.
+
+## Verification Checklist
+
+1. Inspect the Git diff; confirm route paths, API prefixes, permission slugs, and naming.
+2. Review nullable fields, dates, passwords, foreign keys, validation, relationship names; replace generic labels and translations.
+3. Verify list/create/update/delete, authorization, and validation-error behavior.
+4. Run `npm run build:backend` and `npm run build:admin`; run the generated backend tests and add domain coverage.
+
+Generated frontend follows the [React frontend architecture](../../../architecture/react-frontend/Readme.md); review backend modules against the [backend architecture](../../../architecture/backend/Readme.md).