# SPC Convective Outlook API Implementation Plan

## Summary

Implement the `weatherapi` SPC convective outlook API described in [`docs/roadmap/outlook.md`](outlook.md).

This plan is execution-oriented. Implement stages in order. Keep `weatherapi` read-only: it must read `weatherfeeder` Postgres tables, reconstruct canonical model payloads, apply API filters, and present results over HTTP. Do not add ingestion, upstream SPC calls, table creation, migrations, or historical browsing.

Target routes:

- `GET /outlooks/convective`
- `GET /outlooks/convective/active`
- `GET /outlooks/convective/location`

All routes return the existing `data` envelope, support JSON/XML/text, and serve latest-run views only.

## Stage 1: Application Use Case And Filtering

Implement the core use case before touching HTTP or SQL.

Required changes:

- Extend `internal/app.Repository` with:
  - `LatestConvectiveOutlookRun(context.Context) (*model.WeatherOutlookRun, error)`
- Add `internal/app.OutlookFilter` with:
  - `Day *int`
  - `OutlookType string`
  - `ContainsLocation *bool`
  - `ActiveAt *time.Time`
- Add `LatestConvectiveOutlook(ctx context.Context, filter OutlookFilter) (*model.WeatherOutlookRun, error)` to `internal/app.Service`.
- Implement `LatestConvectiveOutlook` by calling `repo.LatestConvectiveOutlookRun(ctx)`, returning `nil, nil` for no run, cloning the run, and filtering the cloned `Outlooks` slice.
- Filtering rules:
  - `Day`: keep outlooks with `outlook.Day == *Day`.
  - `OutlookType`: keep outlooks with exact normalized value matching `outlook.OutlookType`.
  - `ContainsLocation`: keep outlooks with `outlook.ContainsLocation == *ContainsLocation`.
  - `ActiveAt`: keep outlooks where `!ActiveAt.Before(outlook.ValidFrom)` and `ActiveAt.Before(outlook.ValidTo)`.
- Preserve original outlook order.
- Do not mutate the repository-returned run, slice, geometry, or pointer fields.

Tests:

- Add fake repository fields/methods in `internal/app/service_test.go`.
- Test repository delegation and no-data behavior.
- Test each filter independently.
- Test combined filters.
- Test active boundary behavior: includes exact `validFrom`, excludes exact `validTo`.
- Test filtered result keeps run metadata and can return `outlooks: []`.
- Test filtering does not mutate the original run or outlook slice.

Run:

```sh
go test ./internal/app
```

## Stage 2: Postgres Outlook Read Adapter

Add latest-run reconstruction from `weatherfeeder` outlook tables.

Required changes:

- Add `outlooks_queries.go`, `outlooks_rows.go`, `outlooks_mapper.go`, and `outlooks_read.go` under `internal/adapters/outbound/postgres`.
- Query latest parent from `outlook_runs`:
  - selected columns: `event_id`, `location_id`, `location_name`, `latitude`, `longitude`, `as_of`, `issued_at`
  - order: `as_of DESC, event_emitted_at DESC`
  - limit: `1`
- Query child rows from `outlooks` by `run_event_id = $1`, ordered by `outlook_index ASC`.
- Select and map all canonical child columns:
  - `outlook_index`, `outlook_id`, `provider`, `product`, `day`, `outlook_type`, `label`, `label_text`, `severity_rank`, `valid_from`, `valid_to`, `issued_at`, `expires_at`, `forecaster`, `headline`, `summary`, `discussion`, `source_url`, `image_url`, `contains_location`, `geometry_json`
- Map parent row into `model.WeatherOutlookRun` with UTC-normalized `AsOf` and `IssuedAt` pointer.
- Map child row into `model.WeatherOutlook` with UTC-normalized timestamps.
- Convert `geometry_json` into `json.RawMessage` without parsing or reserializing.
- Return `nil, nil` when the latest parent query returns `sql.ErrNoRows`.
- Wrap query, scan, iteration, and geometry decode/conversion failures with operation context.
- Confirm `var _ app.Repository = (*Repository)(nil)` still compiles.

Tests:

- Extend `internal/adapters/outbound/postgres/repository_test.go` or add outlook-specific mapper tests in the same package.
- Test parent nullable mapping and UTC normalization.
- Test child mapping for every canonical field, including `outlook_id`, `provider`, `contains_location`, and `geometry_json`.
- Test nullable fields map to nil/zero omitted model values consistently with existing helpers.
- Test geometry bytes are preserved exactly.
- Add read-path tests following existing repository test style if the package already has DB-backed query tests available; otherwise keep mapper-focused tests and rely on compile-time interface satisfaction.

Run:

```sh
go test ./internal/adapters/outbound/postgres
```

## Stage 3: HTTP Route Definitions And Query Binding

Add route wiring and strict query validation.

Required changes:

- Extend `internal/adapters/inbound/httpapi.Service` with:
  - `LatestConvectiveOutlook(context.Context, app.OutlookFilter) (*model.WeatherOutlookRun, error)`
- Update HTTP test fakes to implement the new method.
- Add `outlooks_endpoint.go` under `internal/adapters/inbound/httpapi`.
- Register outlook definitions from `Definitions(svc)` after weather stories or before discussion; route order should not affect behavior.
- Add an outlook query binder that accepts common `format`, `units`, `tz`, `TZ`, plus outlook-specific filters.
- Reuse existing timezone parsing and common query normalization patterns.
- Validate:
  - `day` must be integer `1`, `2`, or `3`.
  - `outlookType` must be one of `categorical`, `tornado`, `hail`, `wind`; normalize case/space like other common values.
  - `containsLocation` must parse as boolean when allowed.
  - `precision` and unknown params are rejected.
  - `containsLocation` is rejected on `/outlooks/convective/location`.
- Add package-level `outlookNow = time.Now` for active/location filters.
- Route filter construction:
  - `/outlooks/convective`: use user filters only.
  - `/outlooks/convective/active`: add `ActiveAt=outlookNow().UTC()` plus user filters.
  - `/outlooks/convective/location`: add `ActiveAt=outlookNow().UTC()` and `ContainsLocation=true`; reject explicit `containsLocation`.
- Return `response.Envelope{Data: presenter.OutlookRunPayload(run, req.Units, req.Timezone)}`.

Tests:

- Route registration for all three paths.
- JSON success for each route.
- No repository data returns `data: null`.
- Filtered no-match run returns `outlooks: []`.
- `day`, `outlookType`, and `containsLocation` query params construct expected filters.
- Active and location endpoints use deterministic `outlookNow` in tests.
- `precision`, unknown params, invalid day/type/bool, invalid timezone, conflicting `tz`/`TZ`, and `containsLocation` on `/location` return `400 Bad Request`.

Run:

```sh
go test ./internal/adapters/inbound/httpapi
```

## Stage 4: Presenter And Text Template

Add outlook response presentation while preserving canonical shape.

Required changes:

- Add `presenter/outlook.go`.
- Implement `OutlookRunPayload(run *model.WeatherOutlookRun, _ Units, tz *time.Location) any`.
- Return nil for nil input.
- Copy run fields and outlook entries before timestamp conversion.
- Convert run `AsOf`, run `IssuedAt`, outlook `ValidFrom`, `ValidTo`, `IssuedAt`, and `ExpiresAt` with existing timezone helper behavior.
- Preserve `Latitude`, `Longitude`, `SeverityRank`, and `Geometry` without mutating source pointers or slices.
- Keep `units` accepted but ignored.
- Add `templates/outlooks_convective.txt.tmpl`.
- Template should render a clear no-data message when `.Data` is nil and concise outlook summaries when data exists.

Tests:

- Presenter nil input returns nil.
- Timezone conversion affects all run/outlook timestamps and preserves instant.
- Source model is not mutated.
- Geometry bytes are preserved exactly.
- Endpoint text response uses the new template.
- XML response renders without handler error.

Run:

```sh
go test ./internal/adapters/inbound/httpapi/presenter
go test ./internal/adapters/inbound/httpapi
```

## Stage 5: Current-Behavior Documentation

Update docs only after the endpoint behavior is implemented in code.

Required changes:

- Update `README.md` endpoint list with:
  - `GET /outlooks/convective`
  - `GET /outlooks/convective/active`
  - `GET /outlooks/convective/location`
- Update `README.md` query parameter summary to mention outlook filters: `day`, `outlookType`, and `containsLocation`.
- Update `docs/api.md` with an Outlook endpoints section covering:
  - route behavior
  - supported query params and rejected params
  - active filtering semantics
  - `containsLocation` semantics
  - response fields and nullability
  - GeoJSON geometry coordinate order
  - examples for full and location-filtered responses
  - text format note
- Update `docs/internal/http-adapter.md`, `docs/internal/presenters.md`, `docs/internal/postgres-repository.md`, and `docs/integrations/weatherfeeder-postgres.md` only if the implementation adds details not already covered by existing internal/integration docs.
- Do not move implemented behavior into roadmap docs; roadmap docs should remain future/planning context until retired.

Tests:

- No documentation-specific tests are currently required unless existing tests check docs.
- Run full test suite after docs updates to catch template or route registration regressions.

Run:

```sh
go test ./...
```

## Stage 6: Final Verification And Cleanup

Before committing the implementation:

- Run focused tests:

```sh
go test ./internal/app
go test ./internal/adapters/outbound/postgres
go test ./internal/adapters/inbound/httpapi
go test ./internal/adapters/inbound/httpapi/presenter
```

- Run full tests:

```sh
go test ./...
```

- Check status and diff:

```sh
git status --short
git diff --stat
```

- Confirm no unrelated files are included.
- Confirm no weatherfeeder ingestion behavior, schema creation, migration logic, or upstream SPC calls were added.
- Confirm current-behavior docs no longer describe outlook endpoints as future work once implementation is complete, or leave roadmap docs clearly marked as historical/planning if they remain.

## Open Questions

None. The feature roadmap defines the route names, latest-run semantics, filters, adapter ownership, documentation timing, and validation behavior needed for implementation.