118 lines
4.6 KiB
Markdown
118 lines
4.6 KiB
Markdown
# Report Registry Internals
|
|
|
|
This document describes report identity, valid-period resolution, batch
|
|
membership, output naming, artifact grouping, and comparison declarations in
|
|
`internal/report`.
|
|
|
|
## Purpose
|
|
|
|
`internal/report` is the canonical source for report definitions. App, state,
|
|
module building, and CLI wiring consume resolved definitions instead of owning
|
|
report identity policy themselves.
|
|
|
|
## Definition Fields
|
|
|
|
Each report definition declares:
|
|
|
|
- report ID and display name
|
|
- Scriptorium prompt ID
|
|
- generation mode
|
|
- valid-period resolver
|
|
- comparison strategy
|
|
- managed artifact group
|
|
- batch output copy filename
|
|
- generated-report eligibility
|
|
- prior-report compatibility list
|
|
- morning or evening batch membership
|
|
- default ordered module composition
|
|
|
|
Markdown report definitions use the `scriptorium_markdown` generation mode.
|
|
Their template and structured-text schema identifiers are empty. Hourly Report
|
|
declares `generated_text_template` with template ID `hourly` and schema ID
|
|
`hourly`; the app uses those identifiers to validate generated text and render
|
|
the embedded hourly template.
|
|
|
|
## Reports
|
|
|
|
| Report | ID | Prompt | Generation mode | Artifact group | Batch copy | Prior compatibility |
|
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
| Daily Today | `daily_today` | `weather.daily_report` | `scriptorium_markdown` | `daily` | `daily.md` | Daily Today |
|
|
| Tomorrow Report | `tomorrow` | `weather.daily_report` | `scriptorium_markdown` | `tomorrow` | `tomorrow.md` | Tomorrow Report |
|
|
| Hourly Report | `hourly` | `weather.hourly_generated_text` | `generated_text_template` | `hourly` | `hourly.md` | Hourly Report |
|
|
| 3-Day Outlook | `three_day` | `weather.three_day_outlook` | `scriptorium_markdown` | `three-day` | `three-day.md` | 3-Day Outlook |
|
|
| Weekend Outlook | `weekend` | `weather.weekend_outlook` | `scriptorium_markdown` | `weekend` | `weekend.md` | Weekend Outlook |
|
|
| Storm Report | `storm` | `weather.storm_report` | `scriptorium_markdown` | `storm` | `storm.md` | Storm Report |
|
|
|
|
All report definitions are eligible for generation.
|
|
|
|
## Valid Periods
|
|
|
|
- Daily Today covers the selected local civil day, or the current local civil
|
|
day when no date override is supplied.
|
|
- Tomorrow Report covers the next local civil day from generation time.
|
|
- Hourly Report covers the half-open six-hour period from generation time in
|
|
the effective report timezone. The duration is an internal report constant,
|
|
not a configuration field.
|
|
- 3-Day Outlook covers the interval from generation time through local midnight
|
|
three days later.
|
|
- Weekend Outlook covers the upcoming weekend window and is not scheduled for
|
|
Sunday morning batch resolution.
|
|
- Storm Report covers an explicit event window supplied by the caller.
|
|
|
|
Storm event windows can be parsed from local `YYYY-MM-DDTHH:MM` timestamps in
|
|
the configured timezone or RFC3339 timestamps with explicit offsets. End time
|
|
must be after start time.
|
|
|
|
## Boundaries
|
|
|
|
`internal/report` defines report metadata and time coverage. It does not fetch
|
|
weather data, build module values, compare snapshot contents, write state,
|
|
parse CLI flags, or invoke Scriptorium.
|
|
|
|
The CLI owns public command names. The app maps those command names to report
|
|
IDs, then uses the registry for report policy.
|
|
|
|
## Config Fields Used
|
|
|
|
The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch
|
|
output path copying uses batch output names from report definitions. Report
|
|
module overrides can use the `hourly` key for Hourly Report.
|
|
|
|
## Batch Membership
|
|
|
|
Morning batches include Daily Today, 3-Day Outlook, and Weekend Outlook except
|
|
on Sunday. Evening batches include Tomorrow Report. Hourly Report is not part
|
|
of a scheduled batch.
|
|
|
|
## State And App Usage
|
|
|
|
- State paths use `ArtifactGroup`.
|
|
- Batch output copies use `BatchOutputName`.
|
|
- Generation checks `Generated`.
|
|
- Module composition defaults use `Modules`.
|
|
- Prior lookup checks `CompatiblePriorIDs` and the comparison strategy.
|
|
- RunIDs include the resolved report ID.
|
|
|
|
## Failure Behavior
|
|
|
|
- Unknown report IDs and batch names return actionable errors.
|
|
- Weekend Outlook resolution returns an error when resolved directly on Sunday.
|
|
- Storm Report resolution requires start and end, with end after start.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/report/period_test.go`
|
|
- `internal/app/app_test.go`
|
|
- `internal/cli/root_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Report selection goes through the registry.
|
|
- Daily Today and Tomorrow Report both use `weather.daily_report`.
|
|
- Valid periods are half-open intervals independent of rendered report text.
|
|
- Artifact grouping, batch output filenames, generated-report eligibility,
|
|
default module composition, comparison compatibility, and comparison strategy
|
|
are declared by report definition.
|