174 lines
8.2 KiB
Markdown
174 lines
8.2 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.publication.files` adapts immutable results to Core's
|
|
`files.artifact_store` boundary without importing Files internals.
|
|
- `reporting.publication.mail` adapts report notices to Core's
|
|
`mail.notificationDelivery` boundary without importing Mail internals.
|
|
- `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.
|
|
|
|
### Cross-module report providers
|
|
|
|
Source modules contribute aggregate or otherwise minimized reports through
|
|
`reporting.report_provider.<provider-id>`. Core owns contract version `1.0` and
|
|
the provider-neutral DTOs. A provider must declare stable report and revision
|
|
IDs, typed parameters, the complete result schema, privacy transforms,
|
|
retention class, export formats, and re-identification risk. It must enforce
|
|
source access before listing options or producing a result and must return
|
|
source revisions, effective tenant scope, applied transforms, generation time,
|
|
and bounded provenance.
|
|
|
|
Reporting discovers these capabilities by prefix. It validates descriptors,
|
|
rejects undeclared output fields, requires every mandatory transform, records
|
|
purpose and effective audience, and persists immutable execution and export
|
|
evidence. The optional `policy.reporting_governance` capability can tighten
|
|
retention, export formats, required transforms, and high-risk handling. If
|
|
Policy is absent, Reporting applies its restrictive built-in baseline and
|
|
denies high-risk provider reports.
|
|
|
|
This direction is intentionally one-way: source modules import only Core's
|
|
contract and remain usable when Reporting is absent. Reporting never imports
|
|
the source module or reads its ORM tables.
|
|
|
|
## 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 layer deliberately implements a typed expression and semantic
|
|
query language rather than `eval`, arbitrary SQL, stored procedures, or
|
|
runtime scripts. PostgreSQL installations receive parameterized semantic plans
|
|
for filters, grouping, measures, calculated aggregates, sorting, and bounds;
|
|
other engines and pivots use the equivalent bounded runtime evaluator. 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.
|
|
|
|
Aggregate drill-through uses an expiring actor-bound context hash. Resolution
|
|
rechecks all definition and row-policy decisions, verifies the source
|
|
fingerprints against the original execution, preserves the complete dimension
|
|
path, and returns only authorized contributors.
|
|
|
|
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, accessible bar/column/line/area/pie/donut/metric charts,
|
|
drill-through, access explanations, history/provenance, saved views, schedule
|
|
management, Files/Mail publication management, downloads, and a Dashboard
|
|
widget contribution.
|
|
The global `/reports` route is owned only by Reporting. `/reporting` is a
|
|
documented compatibility path. Campaign's module-local aggregate view remains
|
|
at `/campaigns/reports`; when both modules are enabled, the same safe aggregate
|
|
projection is also contributed to the global catalogue through the provider
|
|
contract.
|
|
|
|
## Remaining Product Depth
|
|
|
|
The architecture boundary and first operational vertical are implemented.
|
|
Further work is additive product depth: packaged domain report catalogues,
|
|
XLSX/PDF formatting through optional renderer providers, selector-backed Mail
|
|
profile configuration, external publication connectors, and target-environment
|
|
evidence for a maturity claim above `vertical_slice`.
|