add puzzle training sessions with difficulty and ratings

- /train starts an ephemeral session by choosing easy/medium/hard, banded
  relative to the user's current rating (band width configurable)
- session timer, average per-puzzle time, net rating gain and per-puzzle delta
- next puzzle, plus review and retry reused from the play surface
- explicit stop/start: stopping returns to the difficulty picker
- puzzle rating shown once a puzzle completes, and a side-to-move indicator
- extract the play logic/markup into shared PlayCore and PlayComponents so the
  standalone play view and sessions share one implementation
- sticky footer; glossary entries for Difficulty and Session; ADR 0009
This commit is contained in:
2026-11-05 15:44:11 +01:00
parent c95173cda8
commit 55d2e2a913
19 changed files with 1705 additions and 766 deletions
+16
View File
@@ -59,5 +59,21 @@ defmodule Chesstrainer.Attempts do
|> Repo.one()
end
@doc """
The distinct endgame ids `user_id` has attempted in the last `days` days.
Used by puzzle selection to prefer fresh puzzles; a retry still counts as an
attempt, even though the rating window leaves it unrated.
"""
def recent_endgame_ids(user_id, days \\ 30) do
cutoff = DateTime.add(DateTime.utc_now(), -days, :day)
Attempt
|> where([a], a.user_id == ^user_id and a.inserted_at >= ^cutoff)
|> distinct(true)
|> select([a], a.endgame_id)
|> Repo.all()
end
defp rated(query), do: where(query, [a], not is_nil(a.rated_at))
end
+111
View File
@@ -0,0 +1,111 @@
defmodule Chesstrainer.Puzzles do
@moduledoc """
Selects endgames to serve as puzzles.
A puzzle is played at one of three difficulties — `:easy`, `:medium` or
`:hard` — defined relative to the current user's rating: `:medium` is within
a configurable band of the user's rating, `:easy` below it and `:hard` above
it. The same endgame is therefore easy for one player and hard for another.
Selection prefers endgames the user has not attempted in the last 30 days.
When that pool is empty it falls back to any endgame in the band; the rating
window keeps a recent replay unrated until it expires.
"""
import Ecto.Query, warn: false
alias Chesstrainer.Repo
alias Chesstrainer.Accounts.User
alias Chesstrainer.Attempts
alias Chesstrainer.Endgames.Endgame
@default_band_width 100
@difficulties [:easy, :medium, :hard]
@doc "The difficulties a session can be played at."
def difficulties, do: @difficulties
@doc """
The half-width of the medium band, in rating points.
Configured under `:chesstrainer, :puzzles, :band_width`.
"""
def band_width do
:chesstrainer
|> Application.get_env(:puzzles, [])
|> Keyword.get(:band_width, @default_band_width)
end
@doc """
The `{min, max}` rating range for `difficulty` relative to `rating`.
A `nil` bound is open-ended.
"""
def difficulty_range(rating, difficulty) when difficulty in @difficulties do
width = band_width()
case difficulty do
:easy -> {nil, rating - width}
:medium -> {rating - width, rating + width}
:hard -> {rating + width, nil}
end
end
@doc """
Picks the next puzzle for `user` at `difficulty`, using `user.rating` as the
baseline.
`:exclude_ids` (default `[]`) skips endgames by id — used to avoid repeating
the puzzle just played. Returns `nil` when no endgame exists at all.
"""
def next_endgame(%User{} = user, difficulty, opts \\ [])
when difficulty in @difficulties do
exclude_ids = Keyword.get(opts, :exclude_ids, [])
band = difficulty_range(user.rating, difficulty)
recent_ids = Attempts.recent_endgame_ids(user.id)
fresh =
Endgame
|> in_band(band)
|> skip_ids(exclude_ids)
|> skip_ids(recent_ids)
|> random_one()
fresh || fallback(user.rating, band, exclude_ids)
end
defp fallback(rating, band, exclude_ids) do
Endgame
|> in_band(band)
|> skip_ids(exclude_ids)
|> random_one()
|> case do
nil -> nearest(rating, exclude_ids)
endgame -> endgame
end
end
defp nearest(rating, exclude_ids) do
Endgame
|> skip_ids(exclude_ids)
|> order_by([e], asc: fragment("ABS(? - ?)", e.rating, ^rating))
|> limit(1)
|> Repo.one()
end
defp random_one(query) do
query
|> order_by([e], fragment("RANDOM()"))
|> limit(1)
|> Repo.one()
end
defp in_band(query, {nil, max}), do: where(query, [e], e.rating <= ^max)
defp in_band(query, {min, nil}), do: where(query, [e], e.rating >= ^min)
defp in_band(query, {min, max}),
do: where(query, [e], e.rating >= ^min and e.rating <= ^max)
defp skip_ids(query, []), do: query
defp skip_ids(query, ids), do: where(query, [e], e.id not in ^ids)
end
+13 -2
View File
@@ -27,8 +27,10 @@ defmodule Chesstrainer.Ratings do
Rates both sides of a finished attempt and stamps it as rated.
A solve scores 1 for the user and 0 for the endgame; a failure scores 0 for
the user and 1 for the endgame. Returns `{:ok, %{user, endgame, attempt}}`, or
the user and 1 for the endgame. Returns
`{:ok, %{user, endgame, attempt, user_delta, endgame_delta}}`, or
`{:skipped, attempt}` when the pair was already rated inside the window.
The deltas are the signed change applied to each side's rating.
"""
def rate_attempt(%Attempt{outcome: outcome} = attempt) do
now = DateTime.utc_now(:second)
@@ -74,6 +76,9 @@ defmodule Chesstrainer.Ratings do
end
defp persist(user, endgame, attempt, new_user, new_endgame, now) do
user_delta = new_user.rating - user.rating
endgame_delta = new_endgame.rating - endgame.rating
Repo.transaction(fn ->
user =
user
@@ -96,7 +101,13 @@ defmodule Chesstrainer.Ratings do
|> Ecto.Changeset.change(rated_at: now)
|> Repo.update!()
%{user: user, endgame: endgame, attempt: attempt}
%{
user: user,
endgame: endgame,
attempt: attempt,
user_delta: user_delta,
endgame_delta: endgame_delta
}
end)
end