朱子纯 / vibe-erp

feat(reports): P1.8 — JasperReports integration + built-in ping report

Closes the P1.8 row of the implementation plan — **every Phase 1
platform unit is now ✅**. New platform-reports subproject wrapping
JasperReports 6.21.3 with a minimal api.v1 ReportRenderer facade,
a built-in self-test JRXML template, and a thin HTTP surface.

## api.v1 additions (package `org.vibeerp.api.v1.reports`)

- `ReportRenderer` — injectable facade with ONE method for v1:
    `renderPdf(template: InputStream, data: Map<String, Any?>): ByteArray`
  Caller loads the JRXML (or pre-compiled .jasper) from wherever
  (plug-in JAR classpath, FileStorage, DB metadata row, HTTP
  upload) and hands an open stream to the renderer. The framework
  reads the bytes, compiles/fills/exports, and returns the PDF.
- `ReportRenderException` — wraps any engine exception so plug-ins
  don't have to import concrete Jasper exception types.
- `PluginContext.reports: ReportRenderer` — new optional member
  with the default-throw backward-compat pattern used for every
  other addition. Plug-ins that ship quote PDFs, job cards,
  delivery notes, etc. inject this through the context.

## platform-reports runtime

- `JasperReportRenderer` @Component — wraps JasperReports' compile
  → fill → export cycle into one method.
    * `JasperCompileManager.compileReport(template)` turns the
      JRXML stream into an in-memory `JasperReport`.
    * `JasperFillManager.fillReport(compiled, params, JREmptyDataSource(1))`
      evaluates expressions against the parameter map. The empty
      data source satisfies Jasper's requirement for a non-null
      data source when the template has no `<field>` definitions.
    * `JasperExportManager.exportReportToPdfStream(jasperPrint, buffer)`
      produces the PDF bytes. The `JasperPrint` type annotation on
      the local is deliberate — Jasper has an ambiguous
      `exportReportToPdfStream(InputStream, OutputStream)` overload
      and Kotlin needs the explicit type to pick the right one.
    * Every stage catches `Throwable` and re-throws as
      `ReportRenderException` with a useful message, keeping the
      api.v1 surface clean of Jasper's exception hierarchy.

- `ReportController` at `/api/v1/reports/**`:
    * `POST /ping`    render the built-in self-test JRXML with
                      the supplied `{name: "..."}` (optional, defaults
                      to "world") and return the PDF bytes with
                      `application/pdf` Content-Type
    * `POST /render`  multipart upload a JRXML template + return
                      the PDF. Operator / test use, not the main
                      production path.
  Both endpoints @RequirePermission-gated via `reports.report.render`.

- `reports/vibeerp-ping-report.jrxml` — a single-page JRXML with
  a title, centred "Hello, $P{name}!" text, and a footer. Zero
  fields, one string parameter with a default value. Ships on the
  platform-reports classpath and is loaded by the `/ping` endpoint
  via `ClassPathResource`.

- `META-INF/vibe-erp/metadata/reports.yml` — 1 permission + 1 menu.

## Design decisions captured in-file

- **No template compilation cache.** Every call compiles the JRXML
  fresh. Fine for infrequent reports (quotes, job cards); a hot
  path that renders thousands of the same report per minute would
  want a `ConcurrentHashMap<String, JasperReport>` keyed by
  template hash. Deliberately NOT shipped until a benchmark shows
  it's needed — the cache key semantics need a real consumer.
- **No multiple output formats.** v1 is PDF-only. Additive
  overloads for HTML/XLSX land when a real consumer needs them.
- **No data-source argument.** v1 is parameter-driven, not
  query-driven. A future `renderPdf(template, data, rows)`
  overload will take tabular data for `<field>`-based templates.
- **No Groovy / Janino / ECJ.** The default `JRJavacCompiler` uses
  `javax.tools.ToolProvider.getSystemJavaCompiler()` which is
  available on any JDK runtime. vibe_erp already requires a JDK
  (not JRE) for Liquibase + Flowable + Quartz, so we inherit this
  for free. Zero extra compiler dependencies.

## Config trap caught during first build (documented in build.gradle.kts)

My first attempt added aggressive JasperReports exclusions to
shrink the transitive dep tree (POI, Batik, Velocity, Castor,
Groovy, commons-digester, ...). The build compiled fine but
`JasperCompileManager.compileReport(...)` threw
`ClassNotFoundException: org.apache.commons.digester.Digester`
at runtime — Jasper uses Digester internally to parse the JRXML
structure, and excluding the transitive dep silently breaks
template loading.

Fix: remove ALL exclusions. JasperReports' dep tree IS heavy,
but each transitive is load-bearing for a use case that's only
obvious once you exercise the engine end-to-end. A benchmark-
driven optimization chunk can revisit this later if the JAR size
becomes a concern; for v1.0 the "just pull it all in" approach is
correct. Documented in the build.gradle.kts so the next person
who thinks about trimming the dep tree reads the warning first.

## Smoke test (fresh DB, as admin)

```
POST /api/v1/reports/ping {"name": "Alice"}
  → 200
    Content-Type: application/pdf
    Content-Length: 1436
    body: %PDF-1.5 ... (valid 1-page PDF)

$ file /tmp/ping-report.pdf
  /tmp/ping-report.pdf: PDF document, version 1.5, 1 pages (zip deflate encoded)

POST /api/v1/reports/ping   (no body)
  → 200, 1435 bytes, renders with default name="world" from JRXML
    defaultValueExpression

# negative
POST /api/v1/reports/render  (multipart with garbage bytes)
  → 400 {"message": "failed to compile JRXML template:
         org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1;
         Content is not allowed in prolog."}

GET /api/v1/_meta/metadata
  → permissions includes "reports.report.render"
```

The `%PDF-` magic header is present and the `file` command on
macOS identifies the bytes as a valid PDF 1.5 single-page document.
JasperReports compile + fill + export are all running against
the live JDK 21 javac inside the Spring Boot app on first boot.

## Tests

- 3 new unit tests in `JasperReportRendererTest`:
  * `renders the built-in ping template to a valid PDF byte stream`
    — checks for the `%PDF-` magic header and a reasonable size
  * `renders with the default parameter when the data map is empty`
    — proves the JRXML's defaultValueExpression fires
  * `wraps compile failures in ReportRenderException` — feeds
    garbage bytes and asserts the exception type
- Total framework unit tests: 337 (was 334), all green.

## What this unblocks

- **Printing-shop quote PDFs.** The reference plug-in can now ship
  a `reports/quote.jrxml` in its JAR, load it in an HTTP handler
  via classloader, render via `context.reports.renderPdf(...)`,
  and either return the PDF bytes directly or persist it via
  `context.files.put("reports/quote-$code.pdf", "application/pdf", ...)`
  for later download. The P1.8 → P1.9 chain is ready.
- **Job cards, delivery notes, pick lists, QC certificates.**
  Every business document in a printing shop is a report
  template + a data payload. The facade handles them all through
  the same `renderPdf` call.
- **A future reports PBC.** When a PBC actually needs report
  metadata persisted (template versioning, report scheduling), a
  new pbc-reports can layer on top without changing api.v1 —
  the renderer stays the lowest-level primitive, the PBC becomes
  the management surface.

## Phase 1 completion

With P1.8 landed:

| Unit | Status |
|------|--------|
| P1.2 Plug-in linter        | ✅ |
| P1.3 Plug-in HTTP + lifecycle | ✅ |
| P1.4 Plug-in Liquibase + PluginJdbc | ✅ |
| P1.5 Metadata store + loader | ✅ |
| P1.6 ICU4J translator | ✅ |
| P1.7 Event bus + outbox | ✅ |
| P1.8 JasperReports integration | ✅ |
| P1.9 File store | ✅ |
| P1.10 Quartz scheduler | ✅ |

**All nine Phase 1 platform units are now done.** (P1.1 Postgres RLS
was removed by the early single-tenant refactor, per CLAUDE.md
guardrail #5.) Remaining v1.0 work is cross-cutting: pbc-finance
GL growth, the web SPA (R1–R4), OIDC (P4.2), the MCP server (A1),
and richer per-PBC v2/v3 scopes.

## Non-goals (parking lot)

- Template caching keyed by hash.
- HTML/XLSX exporters.
- Pre-compiled `.jasper` support via a Gradle build task.
- Sub-reports (master-detail).
- Dependency-tree optimisation via selective exclusions — needs a
  benchmark-driven chunk to prove each exclusion is safe.
- Plug-in loader integration for custom font embedding. Jasper's
  default fonts work; custom fonts land when a real customer
  plug-in needs them.