278 lines
15 KiB
Markdown
278 lines
15 KiB
Markdown
# LaDOSE.WebApp
|
||
|
||
Svelte 5 + SvelteKit front-end for `LaDOSE.Api`, styled with Tailwind CSS v4.
|
||
It ships as a static SPA (`@sveltejs/adapter-static`) and talks to the API over
|
||
JWT bearer auth, so it can be served from any static host.
|
||
|
||
## Requirements
|
||
|
||
Node ≥ 22.12 (the toolchain uses Vite 8). An `.nvmrc` is checked in:
|
||
|
||
```bash
|
||
nvm use # resolves lts/*
|
||
npm install
|
||
```
|
||
|
||
## Running
|
||
|
||
The API must be up — it serves on `http://localhost:5000` in development:
|
||
|
||
```bash
|
||
cd ../LaDOSE.Api && dotnet run # terminal 1
|
||
npm run dev # terminal 2 -> http://localhost:5173
|
||
```
|
||
|
||
Point the app at a different API with `VITE_API_BASE_URL` (see `.env.example`).
|
||
`LaDOSE.Api` already allows any origin with credentials, so no dev proxy is needed.
|
||
|
||
## Typed API access
|
||
|
||
`src/lib/api/schema.d.ts` is **generated** from the API's OpenAPI document — never
|
||
edit it by hand. Regenerate whenever a C# controller or DTO changes:
|
||
|
||
```bash
|
||
npm run api:sync # fetch openapi.json from the running API, then re-emit types
|
||
```
|
||
|
||
That is `api:fetch` (curl `/openapi/v1.json`, override the host with `LADOSE_API_URL`)
|
||
followed by `api:types` (`openapi-typescript`). `openapi.json` is committed so the
|
||
types can be rebuilt without a running API.
|
||
|
||
Because paths and DTOs come from the generated types, a renamed route or a changed
|
||
DTO field surfaces as a TypeScript error rather than a runtime 404.
|
||
|
||
| Module | Purpose |
|
||
| --- | --- |
|
||
| `src/lib/api/schema.d.ts` | Generated types — all 31 API paths and every DTO |
|
||
| `src/lib/api/schema-helpers.ts` | Friendly aliases (`ApplicationUserDTO`, `LoginRequest`, …) |
|
||
| `src/lib/api/client.ts` | `apiRequest` — bearer auth, JSON, `ApiError`; paths constrained to real routes |
|
||
| `src/lib/api/users.ts` | `login` against `/Users/auth` — the one unauthenticated call |
|
||
| `src/lib/api/errors.ts` | `toErrorMessage` — message to show, or redirect to `/login` on a 401 |
|
||
| `src/lib/api/tournaments.ts` | `listEvents` / `importSmashTournament` / `getResults`, authenticated from the session |
|
||
| `src/lib/api/games.ts` | `listGames` / `saveGame` / `deleteGame` / `searchSmashGames` |
|
||
| `src/lib/api/admin-users.ts` | `listUsers` / `listRoles` / `addUser` / `deleteUser` — all Admin-only |
|
||
| `src/lib/api/statistics.ts` | `getMatchStats` (set-level win/loss and head to head), `listVersusPlayers` / `getVersus` (one pairing, per game) |
|
||
| `src/lib/api/sheets.ts` | `getSheetsConfig` / `exportToSheets` — writes a ranking table into the club's Google Spreadsheet |
|
||
| `src/lib/tournaments/results.ts` | Pure reshaping of `TournamentsResultDTO`: ranking grid, per-game placements, WordPress HTML, CSV |
|
||
| `src/lib/tournaments/sheet.ts` | Pure: ranking grid → one spreadsheet tab, plus the tab title a selection suggests |
|
||
| `src/lib/statistics/aggregate.ts` | Pure aggregation for `/statistiques`: standings, per-game and per-event summaries, CSV |
|
||
| `src/lib/statistics/load.ts` | `loadEventResults` — per-event `GetResults` fan-out with progress, partial failure and abort |
|
||
| `src/lib/ui/PlayerPicker.svelte` | Filterable player list used twice on `/statistiques/players` |
|
||
| `src/lib/games/draft.ts` | `GameDTO` ⇄ editor form, including the blank-to-NULL rules |
|
||
| `src/lib/ui/classes.ts` | The Tailwind class strings shared by the pages |
|
||
| `src/lib/stores/session.svelte.ts` | Signed-in user, persisted to `localStorage`, drops expired JWTs |
|
||
|
||
Calling another endpoint takes one line, and the path is checked at compile time:
|
||
|
||
```ts
|
||
import { apiRequest, buildPath, session } from '$lib';
|
||
import type { GameDTO } from '$lib';
|
||
|
||
const games = await apiRequest<GameDTO[]>('/api/Game', { token: session.token });
|
||
const one = await apiRequest<GameDTO>(buildPath('/api/Game/{id}', { id: 3 }));
|
||
```
|
||
|
||
## Routes
|
||
|
||
- `/login` — username + password, posts to `POST /Users/auth`, stores the returned JWT
|
||
- `/` — guarded; greets the signed-in user with **Hello, \<name\>.** and offers sign-out
|
||
- `/tournaments` — guarded; the start.gg half of the old Avalonia `TournamentResultView`,
|
||
and the one-click push of the generated ranking table into the club's Google Spreadsheet
|
||
- `/statistiques` — redirects to `/statistiques/rankings` (the path the navbar used before
|
||
the section became two pages)
|
||
- `/statistiques/rankings` — guarded; standings, attendance and match statistics over a
|
||
chosen scope
|
||
- `/statistiques/players` — guarded; two players, every game they met in, all events
|
||
- `/games` — guarded; the game catalogue editor, from the Avalonia `GamesView`
|
||
- `/users` — **Admin only**; add and remove accounts
|
||
|
||
`session.displayName` prefers `firstName lastName` and falls back to `username`.
|
||
|
||
### `/tournaments`
|
||
|
||
Ports the Smash.gg (start.gg) column of `LaDOSE.DesktopApp.Avalonia`:
|
||
|
||
1. **Import** — a slug (`start.gg/tournament/<slug>`) is sent to
|
||
`GET /api/Tournament/ParseSmash/{slug}`, which pulls the brackets, placements and
|
||
sets into the database. Every bracket must be `COMPLETED` or the API throws.
|
||
2. **Events** — `GET /api/Event`, newest first. Tick one event for a single
|
||
tournament, or several to aggregate a ranking season. The regex box replaces the
|
||
selection with every matching event name (e.g. `Ranking #13\d{2}`).
|
||
3. **Generate results** — `POST /api/Tournament/GetResults` with the selected ids;
|
||
the API applies the point rules in `ExternalProviderService`. Three views:
|
||
- *Ranking* — players × games with totals, highest first, plus CSV export and the
|
||
Google Sheets push below
|
||
- *By game* — placements and points for one game
|
||
- *HTML* — the podium table for the WordPress recap, with copy-to-clipboard
|
||
|
||
The Challonge half of the Avalonia view (date range, Challonge tournament list,
|
||
`ParseChallonge`) is deliberately not ported.
|
||
|
||
#### Google Sheets export
|
||
|
||
Next to **Export CSV** on the *Ranking* view: **Push to Google Sheets** writes that same
|
||
table straight into the club's spreadsheet, as one tab. It replaces the
|
||
download-then-import-by-hand step — the tab is the CSV, because `rankingToSheetTable`
|
||
reads the very same `RankingTable` that `buildCsv` does, so the two cannot drift.
|
||
|
||
Because `GetResults` merges everything it is given, selecting `Ranking #1301`, `#1302` and
|
||
`#1303` produces the cumulative table for that ranking day — which is why the tab title
|
||
defaults to the **latest** event in the selection (`Ranking #1303`). Override it in the
|
||
**Tab** box; leaving it blank uses the suggestion shown as the placeholder.
|
||
|
||
- The tab is **cleared and rewritten in place**. Formatting, notes and conditional
|
||
formatting survive (the write only sets `userEnteredValue`), but anything typed into it
|
||
by hand is lost — keep hand analysis in its own tab.
|
||
- Tabs the export does not name are **never touched or deleted**.
|
||
- Re-running changes nothing but the provenance footer's timestamp.
|
||
- Points and totals are written as **numbers**, so formulas over them keep working.
|
||
- Titles are sanitised server-side (Google forbids `: \ / ? * [ ]`, caps at 100 chars);
|
||
any rename is reported back in the success banner.
|
||
- Tab identity is the **title**, so renaming an event makes the next push write a new tab
|
||
beside the old one.
|
||
- The provenance footer, below the grid, names every event scored into the tab — so a
|
||
stale tab says so itself.
|
||
|
||
Server configuration lives in the `GoogleSheets` section — writer, target spreadsheet and
|
||
limits. The target is config-only because the sheet is replaced each year; see
|
||
`.env.example` for the one-time Google setup and the yearly swap. Set
|
||
`GoogleSheets:Writer` to `Logging` to see the exact payload in the API log without
|
||
touching a spreadsheet.
|
||
|
||
### `/statistiques/rankings`
|
||
|
||
**Rankings Statistiques.** Pick a scope — everything, the last 6/12 events, or a regex over event names — then
|
||
**Compute statistics**. Two independent sources feed the page, and they are kept apart
|
||
on purpose:
|
||
|
||
- **Points, placements, attendance** come from `POST /api/Tournament/GetResults`, called
|
||
**one event at a time**. The endpoint merges everything it is given and never says
|
||
which event a row came from, so per-event calls are the only way to get a time series
|
||
— and they contain the damage, because it throws a 500 on any bracket missing a rank-1
|
||
or rank-2 row. One broken import is reported as a skipped event instead of taking the
|
||
whole scope down with it.
|
||
- **Set-level win rates and head to head** come from `POST /api/Statistics/Matches`, in
|
||
a single call for the whole scope.
|
||
|
||
The **Matches** tab leads with its coverage line, and it matters: brackets imported
|
||
before set rows were persisted contribute placements but no matches, so those figures
|
||
can describe a fraction of the scope while the standings above cover all of it. Win
|
||
rates count **decided sets only**, so a player with no resolvable set is left out rather
|
||
than shown at 0%.
|
||
|
||
Other things worth knowing:
|
||
|
||
- Rank `999` is the service's "unplaced" sentinel (the participation bucket in
|
||
`ExternalProviderService`), so it never counts as a placement or a podium, and
|
||
**Best** shows `—`.
|
||
- Player names are merged case-insensitively, as everywhere else in the app.
|
||
- Brackets are counted per event, so a bracket name reused every month counts once
|
||
per event rather than once overall.
|
||
- Undated events sort last in the chart and the Events tab — `GET /api/Event` returns
|
||
newest first, which is the least misleading place to put them.
|
||
- `aggregate.ts` is pure, so it can be exercised under plain Node with fixtures, the
|
||
same way `src/lib/tournaments/results.ts` is.
|
||
|
||
### `/statistiques/players`
|
||
|
||
**Players Statistiques.** Pick two players and the page answers one question: how often
|
||
did they meet, and in which games. There is no event scope — the point of a pairing is
|
||
its whole history, and slicing it by season would only be the Rankings page again.
|
||
|
||
- The pickers come from `GET /api/Statistics/Players`, which lists **tournament
|
||
players** (the rows `set` points at), not the application accounts of `/users`. Only
|
||
players with at least one set in a bracket whose game is known are offered, so the
|
||
list can never suggest a player the breakdown must then report as empty.
|
||
- The breakdown comes from `GET /api/Statistics/Versus/{a}/{b}`, one request per
|
||
complete pairing, aborted and re-issued when either side changes. `winsA` is always
|
||
the first id's side.
|
||
- **A set carries no game.** The game belongs to the `Tournament` the set was played
|
||
in, and `Tournament.GameId` is nullable, so meetings in a bracket with no game cannot
|
||
be filed under one. The API excludes them from `games` and from the totals and counts
|
||
them in `unknownGameSets`; the page reports that number instead of hiding it — it is
|
||
the difference between "they never met" and "we cannot tell what they played".
|
||
- **Meetings** counts every recorded set, **Decided** only those with unequal scores.
|
||
A set with equal scores (including 0-0, and the `-1 / -1` a double DQ leaves behind)
|
||
happened, but nobody won it, so it is in neither record nor game counts. A single DQ
|
||
is stored as `-1` and clamps to zero games.
|
||
- `StatisticsService.AggregateVersus` is a pure static method over already-loaded rows,
|
||
like `Aggregate` beside it, so the win inference is testable without a database.
|
||
|
||
### `/games`
|
||
|
||
Ports `GamesView`: the list on the left (ordered by `Order`), an editor on the right.
|
||
|
||
- **Save** — `POST /api/Game`. `AddOrUpdate` inserts when `id` is 0 and otherwise
|
||
**replaces every column**, so the form always sends a complete `GameDTO`; blank
|
||
text fields are sent as `null`.
|
||
- **New game** — starts an empty draft with `id` 0 and the next free `Order`. The
|
||
desktop app instead posted a blank row immediately and let you fill it in after.
|
||
- **Delete** — `DELETE /api/Game/{id}`, behind a confirm.
|
||
- **Find on start.gg** — `GET /api/Game/smash/{name}` searches start.gg's videogame
|
||
catalogue using the long name (falling back to the name); picking a match fills
|
||
`smashId`. The ids listed are **start.gg** videogame ids, not LaDOSE game ids.
|
||
|
||
`smashId` is what bracket imports match on: a game without one collects its results
|
||
under a synthetic "GAME NOT FOUND" entry.
|
||
|
||
Unlike the desktop form, `imgUrl` is editable here — it is part of `GameDTO` and was
|
||
otherwise only reachable through the database.
|
||
|
||
### `/users` (Admin only)
|
||
|
||
Lists every account with its roles, creates accounts, and deletes them.
|
||
|
||
`POST /Users/register` used to be `[AllowAnonymous]` so that the first account could be
|
||
created. That route is gone; account creation is now `POST /Users/AddUser` and requires
|
||
the **Admin** role, so before this
|
||
page is reachable at all, one account has to be promoted directly in the database:
|
||
|
||
```bash
|
||
# edit the username in the file first, then:
|
||
psql "$LADOSE_DB" -v ON_ERROR_STOP=1 -f ../../Sql/2026-08-05_roles.sql
|
||
```
|
||
|
||
How roles work:
|
||
|
||
- They live in the pre-existing `applicationrole` / `applicationuserrole` tables. The
|
||
script seeds `Admin` and `User`; no schema change was needed.
|
||
- Only user management checks a role. **Every other endpoint is unchanged** — a plain
|
||
or role-less account can still use tournaments, games and the rest.
|
||
- The JWT carries only the user id. Roles are read from the database on every request
|
||
(`OnTokenValidated` in `Startup.cs`), so granting or revoking Admin applies to the
|
||
caller's next request instead of whenever their 16-minute token expires.
|
||
- `session.isAdmin` hides the link and the page, but that is cosmetic — the API is
|
||
what enforces access, and a non-admin calling these endpoints gets a 403.
|
||
- The API refuses to delete the caller's own account. Since only an admin can reach the
|
||
endpoint, that is what guarantees at least one admin always remains.
|
||
|
||
## Notes
|
||
|
||
- The API issues 16-minute tokens. A lapsed token is treated as signed out on load;
|
||
there is no refresh flow yet, so long sessions will need a re-login. The guarded
|
||
pages turn a 401 into a redirect back to `/login` (see `toErrorMessage`).
|
||
- The API has no exception middleware, so an unhandled server error arrives as an
|
||
HTML developer page. `ApiError` then carries only the status, which is why each
|
||
call site supplies its own fallback message.
|
||
- `GetResults` only fills `slug` when **one** event id is requested, so the
|
||
"Voir le Bracket" links appear only for a single-event export.
|
||
- The Sheets export posts a 7-deep body, so `Startup.cs` sets Newtonsoft's `MaxDepth` to
|
||
32. `MaxDepth` governs *reading*; at the previous value of 4 the request was rejected
|
||
before it reached the controller.
|
||
- Player names are merged case-insensitively across brackets, matching the desktop app.
|
||
- `src/routes/+layout.ts` sets `ssr = false`: the JWT lives in the browser, so there
|
||
is nothing meaningful to render on the server.
|
||
|
||
## Checks
|
||
|
||
```bash
|
||
npm run check # svelte-check (types + template diagnostics)
|
||
npm run lint # eslint, including type-aware rules
|
||
npm run test # vitest over the pure modules in $lib
|
||
npm run build # static build into ./build
|
||
```
|
||
|
||
`npm run test` covers `$lib/statistics`, `$lib/tournaments`, `$lib/games/draft` and the
|
||
small shared helpers beside them (`csv`, `events`, `format`). Those modules are pure by
|
||
design, so they run under plain Node with no API and no database.
|