77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
# Weather Data Internals
|
|
|
|
`internal/weatherdata` owns the normalized, wire-independent weather bundle
|
|
that passes from collection through rendering. The Weather API
|
|
adapter translates provider responses into these types; its request, response,
|
|
and availability contract is documented in the
|
|
[Weather API integration guide](../integrations/weatherapi.md).
|
|
|
|
## Bundle contract
|
|
|
|
`Bundle` has a collection timestamp (`FetchedAt`), source provenance
|
|
(`Sources`), and collection-level warnings (`Warnings`). Its product fields are
|
|
optional so an allowed missing source can be represented without manufacturing
|
|
weather data.
|
|
|
|
| Field | Normalized product |
|
|
| --- | --- |
|
|
| `Observation` | Station observation |
|
|
| `Current` | Current conditions |
|
|
| `Hourly` | Hourly forecast periods |
|
|
| `Narrative` | Narrative forecast |
|
|
| `Alerts` | Active-alert check, including an explicitly empty result |
|
|
| `Discussion` | Forecast discussion and its time-range sections |
|
|
| `Daily` | Daily forecast periods when supplied |
|
|
| `WeatherStory` | Latest weather story |
|
|
| `SPCConvectiveOutlooks` | Convective outlook run, discussions, and GeoJSON geometry |
|
|
|
|
The bundle carries values rather than provider request details. Consumers use
|
|
it to construct report facts and data packages; they should not infer a
|
|
provider endpoint or retry policy from the normalized types. See
|
|
[collection](collect.md) for assembly and
|
|
[report templates](../templates.md) for the values exposed to authors.
|
|
|
|
An alert run retains its check time and individual alert payloads for overlap
|
|
selection. Its source entry retains provider provenance; the full provider
|
|
envelope is not carried into the normalized bundle.
|
|
|
|
## Source provenance
|
|
|
|
Every checked source is represented by a `Source` entry. The record identifies
|
|
the source (`Name`), request location and query (`Endpoint`, `Query`), fetch
|
|
time, provider issue and update times when available, a SHA-256 digest of the
|
|
source data, and whether the source was unavailable (`Missing`). Its warnings
|
|
stay with that source in addition to the bundle-level warning list.
|
|
|
|
An empty product can be meaningful checked data. For example, an explicit
|
|
empty alerts result is not missing and retains its source hash. A source is
|
|
marked missing only when the adapter's missing-source policy treats the
|
|
response or parsing failure as unavailable. The policy itself belongs to the
|
|
[configuration reference](../config.md).
|
|
|
|
Accepted hourly forecast periods always have nonzero start and end times, with
|
|
the end after the start. Collection rejects a required hourly product that does
|
|
not meet those bounds before it enters downstream derivation.
|
|
|
|
## Warning semantics
|
|
|
|
`SourceWarning` has a source name, stable code, severity, explanatory message,
|
|
endpoint, and `CompletenessImpact`. When collection proceeds with a warning,
|
|
the same warning appears in `Source.Warnings` and `Bundle.Warnings` so both
|
|
local provenance and whole-run consumers see it. A policy that treats a missing
|
|
source as an error returns no partial bundle.
|
|
|
|
Warnings describe data completeness, not rendering or delivery failures.
|
|
Those failures are reported by [application orchestration](app-orchestration.md).
|
|
|
|
## Boundaries and verification
|
|
|
|
This package defines data shapes and has no HTTP client, configuration loader,
|
|
filesystem access, or template behavior. Focused tests cover the normalized
|
|
types and the Weather API adapter verifies translation into them:
|
|
|
|
```sh
|
|
go test ./internal/weatherdata
|
|
go test ./internal/adapters/weatherapi
|
|
```
|