# 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