[heatherlarange]

Summary

Adds GET /hotels/{id}/freshness, which says when each kind of data was last
successfully updated for a hotel, whether the latest attempt failed, and whether
the data is stale. The manager can then see when rates may be out of date,
and the frontend doesn't need to know the staleness.

Closes #101

Type of change

• feat — new feature
• fix — bug fix
• docs — documentation only
• refactor — code change that neither fixes a bug nor adds a feature
• perf — performance improvement
• test — adding or updating tests
• chore / build / ci — tooling, deps, or pipeline changes

Changes

• API: GET /hotels/{id}/freshness (routes/freshness.py). For each of
  events, weather, hotel_data, and training, it returns last_success,
  last_failure (only when the latest attempt failed or stopped), error and
  stale. An unknown hotel is a 404.
• Service: services/domain/freshness.py holds the rules in one table
  (KINDS):
  • Only routine refreshes count for events (mode: "recent") and weather
    (mode: "forecast"); backfills don't make upcoming rates fresh.
  • Stale after: events and weather 1 day, hotel data 7 days, training 30
    days. Never succeeding is stale.
• Repository: latest_finished_job in repository/job.py, the newest
  finished job of a kind, optionally filtered by status. The second query
  (for the last success) only runs when the latest attempt failed.
• Docs: decision record 0032, index row, and the system
  design file layout and API table.

Database migrations

• No schema changes
• Includes an Alembic migration (just migrate-create "...")
• Migration runs cleanly (just migrate) and rolls back (just migrate-down)

Checklist

• Commits follow Conventional Commits
• Lint passes (just lint) and code is formatted (just format)
• Pre-commit hooks run clean (just hooks installed)
• Updated docs / README / .env.example where relevant
• Tested locally (just dev) and verified the API at http://localhost:8000/docs

How to test

1. just test: the 7 tests in tests/test_freshness.py cover never run,
   succeeded, failed after a success, failed and never succeeded, a success
   clearing an earlier failure, succeeded but stale, and a backfill not
   counting as a refresh.
2. just dev, create a city and hotel, then call
   GET /hotels/{id}/freshness: every kind shows null times and
   stale: true.
3. POST /hotels/{id}/ingest/weather with {}. Once the job succeeds,
   weather shows a last_success and stale: false.
4. GET /hotels/999999/freshness returns 404.

Notes for reviewers

• Recommendation snapshots aren't stored yet, so
  recommendations is always null. When they are stored, it gets one row in
  KINDS.
• The staleness thresholds are a product choice: 1 / 1 / 7 / 30 days.
  Only "events older than a day" came from the ticket.
• Only a failed latest attempt is shown. A failure followed by a success is not shown; it's in
  GET /hotels/{id}/jobs.
• The unit tests use events as the example kind (never run, succeeded,
  failed, stale, and a backfill not counting). All four kinds go through the
  same code; only their row in KINDS differs.