initial

2026-09-23 12:29:08 -03:00
commit f5d231ab8f
59 changed files with 16658 additions and 0 deletions
@@ -0,0 +1,118 @@
+# Create Vitruvio Report
+
+> All messages shown to the user must be written in Portuguese.
+
+You are registering a new report inside a Vitruvio repository. Follow these steps in order.
+
+## Step 1 — Confirm you are inside a Vitruvio repo
+
+```bash
+ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"
+```
+
+If `NOT_A_VITRUVIO_REPO`, stop and tell the user to `cd` into the correct repo.
+
+## Step 2 — Identify the report type
+
+Ask the user which type applies (if not already clear from the request):
+
+| Type | When to use |
+|------|-------------|
+| **MODELO_ESTATICO** | A Jasper report whose layout is fully designed in a `.jrxml` file (Jaspersoft Studio). The dev provides or will provide the `.jrxml`. |
+| **DINAMICO_QUERY_SQL** | A Vitruvio-managed report where data comes from a named query and columns/layout are configured in `vitruvio.json`. The `.jrxml` is still needed but is simpler — Vitruvio drives the structure. |
+
+## Step 3 — Collect details
+
+Ask the user (in a single message, only ask what is missing):
+
+**Both types:**
+- **Key** — kebab-case or snake_case unique identifier.
+- **Name** — human-readable label shown in the UI.
+- **Category** — display category (e.g. `"Compras"`, `"Auditoria/Gondola"`).
+- **Owner** — Vitruvio username of the responsible person.
+- **Orientation** — `RETRATO` (portrait) or `PAISAGEM` (landscape). Default: `RETRATO`.
+- **Allowed groups / users** — who can access this report (can be empty arrays).
+- **Has parameters?** — does the user fill in parameters before running it? If yes, a params form is needed.
+
+**DINAMICO_QUERY_SQL only:**
+- **Query key** — the named query that feeds the report (must be registered in `vitruvio.json`).
+- **Columns** — list of columns: name (DB column), label, alignment (`LEFT`/`CENTER`/`RIGHT`), width (px), aggregation (`null`, `SUM`, `COUNT`, etc.).
+
+## Step 4 — Create the files
+
+### MODELO_ESTATICO
+
+Files live flat in `reports/`:
+- `reports/<key>.jrxml` — **do not generate this file**; tell the user to place the Jaspersoft-designed template here. Must target **JasperReports 6.21.2** — do not save with a newer version.
+- `reports/<key>-params.xml` — only if the report has parameters (follows the same Vaadin XML form schema as panels).
+
+### DINAMICO_QUERY_SQL
+
+Files live in a subdirectory:
+- `reports/<key>/template.jrxml` — **do not generate this file**; tell the user to place the template here.
+- `reports/<key>/params.xml` — only if the report has parameters.
+
+## Step 5 — Register in vitruvio.json
+
+Read `vitruvio.json`, find or create the `"reports"` array, and add the entry.
+
+### MODELO_ESTATICO entry
+
+```json
+{
+  "key": "<key>",
+  "name": "<name>",
+  "type": "MODELO_ESTATICO",
+  "category": "<category>",
+  "owner": "<owner>",
+  "template": "reports/<key>.jrxml",
+  "parameterForm": "reports/<key>-params.xml",
+  "orientation": "RETRATO",
+  "allowedGroups": [],
+  "allowedUsers": [],
+  "columns": [],
+  "schedules": []
+}
+```
+
+Omit `"parameterForm"` if no params form.
+
+### DINAMICO_QUERY_SQL entry
+
+```json
+{
+  "key": "<key>",
+  "name": "<name>",
+  "description": "<description>",
+  "type": "DINAMICO_QUERY_SQL",
+  "category": "<category>",
+  "owner": "<owner>",
+  "template": "reports/<key>/template.jrxml",
+  "parameterForm": "reports/<key>/params.xml",
+  "query": "<query-key>",
+  "orientation": "RETRATO",
+  "allowedGroups": [],
+  "allowedUsers": [],
+  "columns": [
+    {
+      "name": "COLUMN_NAME",
+      "label": "Column Label",
+      "align": "LEFT",
+      "width": 100,
+      "aggregation": null
+    }
+  ]
+}
+```
+
+Omit `"parameterForm"` if no params form.
+
+Preserve the existing file structure and all other entries. Write the updated `vitruvio.json` back.
+
+## Step 6 — Report
+
+Tell the user:
+- Entry registered in `vitruvio.json` with key `<key>` and type `<type>`
+- For MODELO_ESTATICO: remind them to place the `.jrxml` at `reports/<key>.jrxml`, designed in Jaspersoft Studio 6.21.2
+- For DINAMICO_QUERY_SQL: remind them to place the template at `reports/<key>/template.jrxml`
+- If a params form is needed: what file to create and that it follows the same Vaadin XML schema as panels