98 lines
3.5 KiB
Markdown
98 lines
3.5 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,
|
|
briefing, 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
|
|
- valid-period resolver
|
|
- comparison strategy
|
|
- managed artifact group
|
|
- batch output copy filename
|
|
- generated-report eligibility
|
|
- prior-report compatibility list
|
|
- morning or evening batch membership
|
|
|
|
## Implemented Reports
|
|
|
|
| Report | ID | Prompt | Artifact group | Batch copy | Prior compatibility |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| Daily Today | `daily_today` | `weather.daily_report` | `daily` | `daily.md` | Daily Today, Daily Tomorrow |
|
|
| Daily Tomorrow | `daily_tomorrow` | `weather.daily_report` | `daily` | `tomorrow.md` | Daily Today, Daily Tomorrow |
|
|
| 3-Day Outlook | `three_day` | `weather.three_day_outlook` | `three-day` | `three-day.md` | 3-Day Outlook |
|
|
| Weekend Outlook | `weekend` | `weather.weekend_outlook` | `weekend` | `weekend.md` | Weekend Outlook |
|
|
| Storm Report | `storm` | `weather.storm_report` | `storm` | `storm.md` | Storm Report |
|
|
|
|
All implemented 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.
|
|
- Daily Tomorrow covers the next local civil day from generation time.
|
|
- 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 briefings, compare briefing 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.
|
|
|
|
## State And App Usage
|
|
|
|
- State paths use `ArtifactGroup`.
|
|
- Batch output copies use `BatchOutputName`.
|
|
- Generation checks `Generated`.
|
|
- 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 Daily Tomorrow both use `weather.daily_report`.
|
|
- Valid periods are half-open intervals independent of rendered report text.
|
|
- Artifact grouping, batch output filenames, generated-report eligibility,
|
|
comparison compatibility, and comparison strategy are declared by report
|
|
definition.
|