[maria1neu]

Summary

Save each night's recommended rate with its model, range and factors,
and read back a night's latest and previous rate. A night is only
saved again when its model, rate or range changed (decision 0032).
A pricing model with snapshots can't be deleted, so past rates stay.

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

• POST /hotels/{id}/recommendations/snapshots?days=30[&room_type_id=]: prices each night from today (1–90 nights, every room type unless one is given) and saves the rates that changed. Returns only the snapshots saved.
• GET /hotels/{id}/recommendations/snapshot?date=[&room_type_id=]: a night's latest and previous snapshot, plus change (latest minus previous, in €). A future night with no snapshot is priced and saved now; a past night with none is a 404.
• GET /hotels/{id}/recommendations is unchanged. It still saves nothing and works as a preview.

Model / database

• New recommendation_snapshots table: hotel, room type, stay date, model id and version, rate, interval low/high, uncertainty, factors (JSONB), created at. The migration upgrades and downgrades cleanly.
• model_id is ON DELETE NO ACTION: a pricing model with snapshots can't be deleted, so past rates stay as they were. Deleting a hotel still removes its snapshots.

Business logic

• A night is saved again only when its model, rate or range changed since its latest snapshot (decision 0032). Uncertainty and factors are stored but don't trigger a new row.
• Snapshots are only added, never updated. Past nights are never created after the fact.

Docs and tests

• Decision 0032 is added and docs/system-design.md is updated (table, routes, foreign-key rule, scheduling note).
• 13 tests in backend/tests/test_recommendation_snapshots.py.

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

Notes for reviewers