130 lines
5.7 KiB
Markdown
130 lines
5.7 KiB
Markdown
# Reporting Module Boundary
|
|
|
|
`govoplan-reporting` owns report definitions, execution, dashboards, BI views,
|
|
scheduled outputs, and report exports. It may use templates for formatted
|
|
outputs, but it owns the report data and publication semantics.
|
|
|
|
The core boundary decision register is in
|
|
`/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`.
|
|
|
|
## Ownership
|
|
|
|
Reporting owns:
|
|
|
|
- report definitions, parameters, saved views, and dashboard cards
|
|
- curated query/view inputs from modules, connectors, datasources, or
|
|
configuration packages
|
|
- report execution history, generated output evidence, and scheduled runs
|
|
- institutional question, goal/obligation, owner, calculation-version,
|
|
freshness/quality, and decision/action-consumption references for each
|
|
material report or indicator
|
|
- report permissions and sharing rules
|
|
- export targets such as file, DMS, mail, API, RSS/Atom publication, and
|
|
downstream connector handoff
|
|
- BI-style summaries where GovOPlaN owns the underlying process evidence
|
|
|
|
## Source Inputs
|
|
|
|
Initial source categories:
|
|
|
|
- module-owned read models and summary DTOs
|
|
- curated SQL/query views exposed through a controlled capability
|
|
- connector-staged datasets and external references
|
|
- generated file/csv/xlsx inputs from files/connectors
|
|
- governed `govoplan-datasources` catalogue entries and immutable
|
|
materializations
|
|
- versioned `govoplan-dataflow` outputs and run lineage
|
|
|
|
Reporting should not reach into module ORM internals directly. Module-owned
|
|
data must be exposed through capabilities, DTOs, events, read models, or
|
|
controlled query views.
|
|
|
|
Every reproducible report definition should retain or resolve:
|
|
|
|
- the institutional question, obligation, goal, or service measure it serves;
|
|
- owner and responsible organization/function;
|
|
- datasource/materialization and Dataflow definition/run revisions;
|
|
- source freshness, quality state, known limitations, and calculation version;
|
|
- purpose, visibility, privacy, retention, and publication decisions;
|
|
- reports, decisions, controls, projects, or actions that consumed the result.
|
|
|
|
Reporting owns execution and presentation of the measure. Mandates, Services,
|
|
Projects, Risk Compliance, Decisions, and other domains retain ownership of
|
|
the referenced institutional concepts.
|
|
|
|
## Output Targets
|
|
|
|
- dashboard/widget view
|
|
- API result
|
|
- downloadable file
|
|
- stored file/DMS evidence
|
|
- email attachment or link through mail
|
|
- scheduled export
|
|
- RSS/Atom/open-data publication through connectors
|
|
- workflow/task notification when a report run needs review
|
|
|
|
## Boundaries
|
|
|
|
Reporting does not own:
|
|
|
|
- reusable template rendering; that belongs to `govoplan-templates`
|
|
- DMS lifecycle, collaborative editing, legal hold, or records management
|
|
- raw file/blob storage and provider connectors
|
|
- ingestion, governed source identity, staging, or transformation pipeline
|
|
ownership; those belong to Connectors, Datasources, and Dataflow
|
|
- cross-module search indexing; that belongs to `govoplan-search`
|
|
|
|
## Capability Contracts
|
|
|
|
- `reporting.registry` owns immutable definition registration and lookup.
|
|
- `reporting.runner` executes exact report graphs and returns governed result
|
|
evidence.
|
|
- `reporting.scheduler` claims due schedules and preserves run/publication
|
|
outcomes.
|
|
- `reporting.chart_renderer` renders provider-neutral visual models with an
|
|
accessible table fallback.
|
|
- `reporting.read_model:*` capabilities can expose bounded source-owned rows.
|
|
- `reporting.publication_target:*` capabilities can accept immutable result
|
|
payloads without Reporting importing the target module.
|
|
|
|
## Implemented Vertical
|
|
|
|
The first complete vertical persists datasets, semantic models, reports,
|
|
quality plans, grants, executions, saved views, schedules, publications,
|
|
quality results, and import assessments. Each definition update creates an
|
|
immutable revision and requires optimistic concurrency. Active child
|
|
definitions require the exact pinned parent revision to be active.
|
|
|
|
Execution resolves the report, semantic model, and dataset graph before
|
|
reading data. Static fixtures, Dataflow output, and provider-owned read models
|
|
share one bounded read contract. Source fingerprints, freshness, schema,
|
|
row-policy provenance, blocking quality plans, definition hashes, executor
|
|
version, output hash, diagnostics, and authorized rows are retained with the
|
|
execution. Failed runs also retain evidence.
|
|
|
|
The query engine deliberately implements a typed expression and semantic
|
|
query language rather than `eval`, arbitrary SQL, stored procedures, or
|
|
runtime scripts. It supports detail, grouped summary, pivot, dimensions,
|
|
hierarchies, common aggregates, calculated measures, filters, sorting,
|
|
pagination, totals, and a provider-neutral visualization model. A saved chart
|
|
that is incompatible with an ad-hoc query degrades to its mandatory table
|
|
fallback instead of failing a valid report run.
|
|
|
|
Direct export supports UTF-8 CSV and JSON. CSV cells that spreadsheet software
|
|
could interpret as formulas are escaped. Additional formats and delivery
|
|
destinations use an optional publication capability and preserve idempotent
|
|
evidence. Import assessments classify exact, approximated, and unsupported
|
|
semantics and block activation until every approximation is accepted and no
|
|
unsupported executable behavior remains.
|
|
|
|
The WebUI uses the platform module loader and common controls. It exposes a
|
|
report catalogue, parameter and semantic-query controls, result visualization
|
|
and table views, history/provenance, saved views, schedules, and downloads.
|
|
|
|
## Remaining Product Depth
|
|
|
|
The architecture boundary is implemented. Further work is additive product
|
|
depth: richer visualization providers, drill-through navigation, packaged
|
|
domain report catalogues, XLSX/PDF formatting through optional providers, and
|
|
target-environment evidence for a maturity claim above `vertical_slice`.
|