127 lines
4.6 KiB
Markdown
127 lines
4.6 KiB
Markdown
# Distributor Report Paths Roadmap
|
|
|
|
## Purpose
|
|
|
|
This roadmap defines the target behavior for naming Markdown reports inside
|
|
distributor source bundles.
|
|
|
|
Weatherreporter currently uses one application-level
|
|
`notify.distributor.report_path_templates` list for every report type. That
|
|
model is too coarse for the intended output layout because different reports
|
|
need different archive paths, latest paths, and report-specific aliases.
|
|
|
|
## Locked Decisions
|
|
|
|
- Remove `notify.distributor.report_path_templates`; do not keep a legacy
|
|
fallback or compatibility alias.
|
|
- Report definitions own canonical distributor output path templates.
|
|
- Configuration may override distributor output path templates per report.
|
|
- The app layer resolves report-specific distributor bundle paths before
|
|
calling the distributor adapter.
|
|
- The distributor adapter continues to receive explicit source-to-bundle file
|
|
mappings and does not choose report types, render templates, scan
|
|
workspaces, or apply report routing policy.
|
|
- Managed Markdown report files remain the only distributor upload sources.
|
|
Optional local output copies are not uploaded.
|
|
- Batch distributor uploads, when enabled, use the same report-specific bundle
|
|
path resolver for each included report.
|
|
- Non-roadmap documentation must not describe this behavior until it is
|
|
implemented.
|
|
|
|
## Target Configuration Model
|
|
|
|
The global path template list is removed from `notify.distributor`:
|
|
|
|
```yaml
|
|
notify:
|
|
distributor:
|
|
enabled: false
|
|
endpoint: https://distributor.example.com
|
|
token_env: DISTRIBUTOR_UPLOAD_TOKEN
|
|
timeout: 30s
|
|
failure_policy: error
|
|
pipeline_id_template: "weatherreporter.{report_id}"
|
|
bundle_id_template: "weatherreporter.{location_id}.{report_id}"
|
|
idempotency_key_template: "{bundle_id}.{run_id}"
|
|
```
|
|
|
|
Per-report overrides live under `reports.<report>.distributor`:
|
|
|
|
```yaml
|
|
reports:
|
|
daily:
|
|
distributor:
|
|
path_templates:
|
|
- "daily/{valid_start_date}/{run_id}.md"
|
|
- "daily/{valid_start_date}/index.md"
|
|
```
|
|
|
|
If a report override is omitted, weatherreporter uses the defaults declared by
|
|
that report definition.
|
|
|
|
## Default Report Paths
|
|
|
|
Each generated report maps its managed Markdown source file to one or more
|
|
bundle-relative distributor paths.
|
|
|
|
| Report | Default distributor paths |
|
|
| --- | --- |
|
|
| `hourly` | `hourly/index.md` |
|
|
| `daily` | `daily/{valid_start_date}/{run_id}.md`; `daily/{valid_start_date}/index.md` |
|
|
| `today` | `daily/{valid_start_date}/{run_id}.md`; `daily/{valid_start_date}/index.md`; `today/index.md` |
|
|
| `tomorrow` | `daily/{valid_start_date}/{run_id}.md`; `daily/{valid_start_date}/index.md`; `tomorrow/index.md` |
|
|
| `three_day` | `three-day/{valid_start_date}/{run_id}.md`; `three-day/{valid_start_date}/index.md` |
|
|
| `weekend` | `weekend/{valid_start_date}/{run_id}.md`; `weekend/{valid_start_date}/index.md` |
|
|
| `storm` | `storm/{storm_id}/{run_id}.md`; `storm/{storm_id}/index.md` |
|
|
|
|
`storm_id` is derived from the resolved storm valid period until a future
|
|
explicit storm identity source exists.
|
|
|
|
## Template Values
|
|
|
|
Report path templates keep the existing report template values:
|
|
|
|
- `location_id`
|
|
- `report_id`
|
|
- `run_id`
|
|
- `artifact_group`
|
|
- `batch_output_name`
|
|
- `valid_start_date`
|
|
- `valid_end_date`
|
|
- `valid_start_time`
|
|
- `valid_end_time`
|
|
- `valid_start_stamp`
|
|
- `valid_end_stamp`
|
|
- `storm_id`
|
|
|
|
The initial `storm_id` value is `{valid_start_stamp}-{valid_end_stamp}` in the
|
|
effective report timezone. It is available for all single-report distributor
|
|
templates, but it renders as an empty value for non-storm reports.
|
|
|
|
Rendered paths must stay unique relative paths using `/` separators. They must
|
|
not contain backslashes, empty path segments, `.`, `..`, `manifest.json`, or
|
|
`.distributor.json`.
|
|
|
|
## Intended Final State
|
|
|
|
`internal/report.Definition` declares distributor path defaults alongside the
|
|
other report-owned behavior such as report ID, prompt ID, valid-period
|
|
resolution, module composition, comparison strategy, artifact group, and output
|
|
name.
|
|
|
|
`internal/config` owns per-report override loading and validation. Unknown
|
|
fields under report config continue to fail validation or YAML unmarshalling.
|
|
|
|
`internal/app` resolves bundle paths through one helper used by both
|
|
single-report notification and batch notification. That helper applies this
|
|
precedence:
|
|
|
|
1. `reports.<report>.distributor.path_templates`, when explicitly configured.
|
|
2. `report.Definition` distributor path defaults.
|
|
|
|
There is no third global fallback.
|
|
|
|
The distributor adapter API remains unchanged unless a separate adapter concern
|
|
requires it. It should still upload the explicit file mappings passed by the
|
|
app layer.
|