feat: align docs with code, finish_place, registered status, UI filters, tests, CI

- Add PLAN.md and sync backend docs, .env.example, API doc (404 details)
- Document mock DB and PORT/API_PORT in docs/backend.md; README monorepo + frontend/.env.example
- Migration 002: finish_place column, status registered; mapper and mock DB updated
- Frontend: registered status, finishPlace, calendar year/month filters, pace sparkline
- Extract createApp for tests; supertest + tsx; GitHub Actions CI

Made-with: Cursor

frontend/.env.example

@@ -0,0 +1,2 @@
+# Base URL of the Calendar Run API (must match CORS_ORIGIN on the backend)
+VITE_API_BASE_URL=http://localhost:3001

frontend/package-lock.json

@@ -52,7 +52,6 @@
       "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.29.0",
         "@babel/generator": "^7.29.0",
@@ -1169,7 +1168,6 @@
       "integrity": "sha512-wGdMcf+vPYM6jikpS/qhg6WiqSV/OhG+jeeHT/KlVqxYfD40iYJf9/AE1uQxVWFvU7MipKRkRv8NSHiCGgPr8Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -1187,7 +1185,6 @@
       "integrity": "sha512-z9VXpC7MWrhfWipitjNdgCauoMLRdIILQsAEV+ZesIzBq/oUlxk0m3ApZuMFCXdnS4U7KrI+l3WRUEGQ8K1QKw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/prop-types": "*",
         "csstype": "^3.2.2"
@@ -1257,7 +1254,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.10.12",
         "caniuse-lite": "^1.0.30001782",
@@ -1534,7 +1530,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
       "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0"
       },
@@ -1547,7 +1542,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
       "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0",
         "scheduler": "^0.23.2"
@@ -1730,7 +1724,6 @@
       "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",

frontend/src/api/races.ts

@@ -18,13 +18,17 @@ function normalizeRace(input: unknown): Race {
     isString(race?.date) &&
     isString(race?.title) &&
     typeof race?.distanceKm === "number" &&
-    (race?.status === null || race?.status === "planned" || race?.status === "completed") &&
+    (race?.status === null ||
+      race?.status === "planned" ||
+      race?.status === "registered" ||
+      race?.status === "completed") &&
     isNullableString(race?.officialUrl) &&
     isNullableString(race?.startTime) &&
     isNullableString(race?.clusterSchedule) &&
     isNullableString(race?.bibPickup) &&
     isNullableString(race?.bibNumber) &&
     isNullableString(race?.finishTime) &&
+    isNullableString(race?.finishPlace) &&
     isNullableString(race?.notes) &&
     isString(race?.createdAt) &&
     (race?.updatedAt === null || isString(race?.updatedAt));
@@ -49,6 +53,7 @@ function normalizeRace(input: unknown): Race {
     bibPickup: race.bibPickup,
     bibNumber: race.bibNumber,
     finishTime: race.finishTime,
+    finishPlace: race.finishPlace,
     notes: race.notes,
     createdAt: race.createdAt,
     updatedAt: race.updatedAt,

frontend/src/api/types.ts

@@ -1,4 +1,4 @@
-export type RaceStatus = "planned" | "completed";
+export type RaceStatus = "planned" | "registered" | "completed";
 
 export interface Race {
   id: string;
@@ -12,6 +12,7 @@ export interface Race {
   bibPickup: string | null;
   bibNumber: string | null;
   finishTime: string | null;
+  finishPlace: string | null;
   notes: string | null;
   createdAt: string;
   updatedAt: string | null;
@@ -34,6 +35,7 @@ export interface CreateRacePayload {
   bibPickup?: string | null;
   bibNumber?: string | null;
   finishTime?: string | null;
+  finishPlace?: string | null;
   notes?: string | null;
 }
 

frontend/src/components/PaceTrendChart.tsx

@@ -0,0 +1,73 @@
+import type { Race } from "../api";
+import { formatRaceDate, isCloseDistance, parseFinishTimeToSeconds } from "../lib";
+
+type PaceTrendChartProps = {
+  races: Race[];
+  distanceKm: number;
+};
+
+/**
+ * Minimal SVG sparkline: finish time (minutes) over chronological completed races
+ * at the selected distance. Lower time = higher point (better).
+ */
+export function PaceTrendChart(props: PaceTrendChartProps): JSX.Element {
+  const { races, distanceKm } = props;
+
+  const series = races
+    .filter(
+      (race) =>
+        race.status === "completed" &&
+        isCloseDistance(race.distanceKm, distanceKm) &&
+        parseFinishTimeToSeconds(race.finishTime) != null,
+    )
+    .sort(
+      (a, b) => new Date(`${a.date}T00:00:00`).getTime() - new Date(`${b.date}T00:00:00`).getTime(),
+    )
+    .map((race) => {
+      const seconds = parseFinishTimeToSeconds(race.finishTime)!;
+      return { race, minutes: seconds / 60 };
+    });
+
+  if (series.length < 2) {
+    return (
+      <p className="pace-chart__empty">
+        Нужно минимум два завершённых старта с временем на выбранной дистанции.
+      </p>
+    );
+  }
+
+  const minutes = series.map((s) => s.minutes);
+  const minM = Math.min(...minutes);
+  const maxM = Math.max(...minutes);
+  const range = maxM - minM || 1;
+  const n = series.length;
+
+  const pad = 4;
+  const w = 100;
+  const h = 36;
+  const innerW = w - pad * 2;
+  const innerH = h - pad * 2;
+
+  const points = series
+    .map((s, i) => {
+      const x = pad + (n === 1 ? innerW / 2 : (i / (n - 1)) * innerW);
+      const norm = (maxM - s.minutes) / range;
+      const y = pad + (1 - norm) * innerH;
+      return `${x},${y}`;
+    })
+    .join(" ");
+
+  const last = series[series.length - 1]!;
+
+  return (
+    <div className="pace-chart">
+      <svg className="pace-chart__svg" viewBox={`0 0 ${w} ${h}`} role="img" aria-label="Динамика времени на дистанции">
+        <polyline className="pace-chart__line" fill="none" points={points} />
+      </svg>
+      <p className="pace-chart__caption">
+        Последний пункт: {formatRaceDate(last.race.date)} — {last.race.finishTime} (
+        {last.minutes.toFixed(1)} мин)
+      </p>
+    </div>
+  );
+}

frontend/src/components/index.ts

@@ -1 +1 @@
-export {};
+export { PaceTrendChart } from "./PaceTrendChart";

frontend/src/lib/index.ts

@@ -3,7 +3,9 @@ export {
   formatRaceDate,
   getPaceLabel,
   getRaceCountdownLabel,
+  getRaceStatusClassName,
   getRaceStatusLabel,
+  isCloseDistance,
   parseFinishTimeToSeconds,
   sortByDateAsc,
   sortByDateDesc,

frontend/src/lib/raceMetrics.ts

@@ -89,6 +89,10 @@ export function getRaceCountdownLabel(date: string, now: Date = new Date()): str
   return `через ${days} дней`;
 }
 
+export function isCloseDistance(left: number, right: number): boolean {
+  return Math.abs(left - right) < 0.05;
+}
+
 export function getPaceLabel(finishTime: string | null, distanceKm: number): string | null {
   const totalSeconds = parseFinishTimeToSeconds(finishTime);
   if (!totalSeconds || distanceKm <= 0) {
@@ -102,9 +106,23 @@ export function getPaceLabel(finishTime: string | null, distanceKm: number): str
   return `${String(paceMinutes).padStart(2, "0")}:${String(paceRemainder).padStart(2, "0")} /км`;
 }
 
+export function getRaceStatusClassName(status: Race["status"]): string {
+  const base = "race-card__status";
+  if (status === "completed") {
+    return `${base} ${base}--completed`;
+  }
+  if (status === "registered") {
+    return `${base} ${base}--registered`;
+  }
+  return `${base} ${base}--planned`;
+}
+
 export function getRaceStatusLabel(status: Race["status"]): string {
   if (status === "completed") {
     return "пробежал";
   }
+  if (status === "registered") {
+    return "зарегистрирован";
+  }
   return "планирую";
 }

frontend/src/pages/DashboardPage.tsx

@@ -1,11 +1,13 @@
 import { useEffect, useMemo, useState } from "react";
 import type { Race } from "../api";
 import { ApiError, getRaces } from "../api";
+import { PaceTrendChart } from "../components";
 import {
   formatDistance,
   formatRaceDate,
   getRaceCountdownLabel,
   getPaceLabel,
+  isCloseDistance,
   parseFinishTimeToSeconds,
   splitRacesByDate,
 } from "../lib";
@@ -19,14 +21,11 @@ function getErrorMessage(error: unknown): string {
   return "Не удалось загрузить данные dashboard.";
 }
 
-function isSameDistance(left: number, right: number): boolean {
-  return Math.abs(left - right) < 0.05;
-}
-
 export function DashboardPage(): JSX.Element {
   const [races, setRaces] = useState<Race[]>([]);
   const [isLoading, setIsLoading] = useState<boolean>(true);
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [chartDistanceKm, setChartDistanceKm] = useState<number>(10);
 
   useEffect(() => {
     let isMounted = true;
@@ -98,7 +97,7 @@ export function DashboardPage(): JSX.Element {
       const candidates = races.filter((race) => {
         return (
           race.status === "completed" &&
-          isSameDistance(race.distanceKm, distanceKm) &&
+          isCloseDistance(race.distanceKm, distanceKm) &&
           Boolean(parseFinishTimeToSeconds(race.finishTime))
         );
       });
@@ -136,7 +135,7 @@ export function DashboardPage(): JSX.Element {
         distance: formatDistance(race.distanceKm),
         finishTime: race.finishTime ?? "время не указано",
         pace: getPaceLabel(race.finishTime, race.distanceKm) ?? "не удалось вычислить",
-        place: "нет данных",
+        place: race.finishPlace?.trim() ? race.finishPlace : "нет данных",
       }))
       .sort((left, right) => right.year - left.year || left.title.localeCompare(right.title, "ru-RU"));
   }, [races]);
@@ -218,6 +217,30 @@ export function DashboardPage(): JSX.Element {
         </article>
       </div>
 
+      <section className="dashboard-section" aria-label="Динамика времени на дистанции">
+        <h2 className="dashboard-section__title">Прогресс по времени</h2>
+        <p className="dashboard-section__intro">
+          Линия по завершённым стартам выбранной дистанции: выше — лучше время (короче гонка).
+        </p>
+        <label className="races-filter__field">
+          <span className="races-filter__label">Дистанция для графика</span>
+          <select
+            className="races-filter__select"
+            value={String(chartDistanceKm)}
+            onChange={(event) => {
+              setChartDistanceKm(Number(event.target.value));
+            }}
+          >
+            {PR_DISTANCES.map((d) => (
+              <option key={d} value={d}>
+                {formatDistance(d)}
+              </option>
+            ))}
+          </select>
+        </label>
+        <PaceTrendChart races={races} distanceKm={chartDistanceKm} />
+      </section>
+
       <section className="dashboard-section" aria-label="Личные рекорды по дистанциям">
         <h2 className="dashboard-section__title">PR по дистанциям</h2>
         <div className="dashboard-grid dashboard-grid--pr">

frontend/src/pages/RaceDetailsPage.tsx

@@ -1,7 +1,13 @@
 import { useEffect, useMemo, useState } from "react";
 import { Link, useParams } from "react-router-dom";
 import { ApiError, getRaceById } from "../api";
-import { formatDistance, formatRaceDate, getPaceLabel, getRaceStatusLabel } from "../lib";
+import {
+  formatDistance,
+  formatRaceDate,
+  getPaceLabel,
+  getRaceStatusClassName,
+  getRaceStatusLabel,
+} from "../lib";
 import type { Race } from "../api";
 
 function getErrorMessage(error: unknown): string {
@@ -91,15 +97,7 @@ export function RaceDetailsPage(): JSX.Element {
             {formatRaceDate(race.date)} · {formatDistance(race.distanceKm)}
           </p>
         </div>
-        <span
-          className={
-            isCompleted
-              ? "race-card__status race-card__status--completed"
-              : "race-card__status race-card__status--planned"
-          }
-        >
-          {getRaceStatusLabel(race.status)}
-        </span>
+        <span className={getRaceStatusClassName(race.status)}>{getRaceStatusLabel(race.status)}</span>
       </div>
 
       <div className="race-details-grid">
@@ -133,6 +131,12 @@ export function RaceDetailsPage(): JSX.Element {
                 <dt className="race-details-meta__key">Темп</dt>
                 <dd className="race-details-meta__value">{paceLabel ?? "не удалось вычислить"}</dd>
               </div>
+              <div className="race-details-meta__item">
+                <dt className="race-details-meta__key">Место</dt>
+                <dd className="race-details-meta__value">
+                  {race.finishPlace?.trim() ? race.finishPlace : "не указано"}
+                </dd>
+              </div>
               <div className="race-details-meta__item">
                 <dt className="race-details-meta__key">Стартовый номер</dt>
                 <dd className="race-details-meta__value">{race.bibNumber ?? "не указан"}</dd>

frontend/src/pages/RacesPage.tsx

@@ -1,8 +1,41 @@
 import { useEffect, useMemo, useState } from "react";
 import { Link } from "react-router-dom";
-import type { Race } from "../api";
+import type { Race, RacesQuery } from "../api";
 import { ApiError, getRaces } from "../api";
-import { formatDistance, formatRaceDate, getRaceStatusLabel, splitRacesByDate } from "../lib";
+import {
+  formatDistance,
+  formatRaceDate,
+  getRaceStatusClassName,
+  getRaceStatusLabel,
+  splitRacesByDate,
+} from "../lib";
+
+const MONTH_OPTIONS: { value: string; label: string }[] = [
+  { value: "", label: "Все месяцы" },
+  { value: "1", label: "Январь" },
+  { value: "2", label: "Февраль" },
+  { value: "3", label: "Март" },
+  { value: "4", label: "Апрель" },
+  { value: "5", label: "Май" },
+  { value: "6", label: "Июнь" },
+  { value: "7", label: "Июль" },
+  { value: "8", label: "Август" },
+  { value: "9", label: "Сентябрь" },
+  { value: "10", label: "Октябрь" },
+  { value: "11", label: "Ноябрь" },
+  { value: "12", label: "Декабрь" },
+];
+
+function yearSelectOptions(): number[] {
+  const current = new Date().getFullYear();
+  const start = current - 2;
+  const end = current + 4;
+  const years: number[] = [];
+  for (let y = start; y <= end; y += 1) {
+    years.push(y);
+  }
+  return years;
+}
 
 function getErrorMessage(error: unknown): string {
   if (error instanceof ApiError) {
@@ -31,15 +64,7 @@ function RaceList(props: { title: string; races: Race[] }): JSX.Element {
                   {formatRaceDate(race.date)} · {formatDistance(race.distanceKm)}
                 </p>
               </div>
-              <span
-                className={
-                  race.status === "completed"
-                    ? "race-card__status race-card__status--completed"
-                    : "race-card__status race-card__status--planned"
-                }
-              >
-                {getRaceStatusLabel(race.status)}
-              </span>
+              <span className={getRaceStatusClassName(race.status)}>{getRaceStatusLabel(race.status)}</span>
             </li>
           ))}
         </ul>
@@ -54,13 +79,33 @@ export function RacesPage(): JSX.Element {
   const [races, setRaces] = useState<Race[]>([]);
   const [isLoading, setIsLoading] = useState<boolean>(true);
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [yearFilter, setYearFilter] = useState<string>("");
+  const [monthFilter, setMonthFilter] = useState<string>("");
+
+  const listQuery = useMemo((): RacesQuery | undefined => {
+    const q: RacesQuery = {};
+    if (yearFilter !== "") {
+      const y = parseInt(yearFilter, 10);
+      if (!Number.isNaN(y)) {
+        q.year = y;
+      }
+    }
+    if (monthFilter !== "") {
+      const m = parseInt(monthFilter, 10);
+      if (!Number.isNaN(m)) {
+        q.month = m;
+      }
+    }
+    return Object.keys(q).length > 0 ? q : undefined;
+  }, [yearFilter, monthFilter]);
 
   useEffect(() => {
     let isMounted = true;
 
     async function loadRaces(): Promise<void> {
+      setIsLoading(true);
       try {
-        const items = await getRaces();
+        const items = await getRaces(listQuery);
         if (!isMounted) {
           return;
         }
@@ -82,20 +127,11 @@ export function RacesPage(): JSX.Element {
     return () => {
       isMounted = false;
     };
-  }, []);
+  }, [listQuery]);
 
   const { upcoming, past } = useMemo(() => splitRacesByDate(races), [races]);
 
-  if (isLoading) {
-    return (
-      <section className="page page--races" aria-busy="true">
-        <h1 className="page__title">Календарь стартов</h1>
-        <p className="page__subtitle">Загружаем данные...</p>
-      </section>
-    );
-  }
-
-  if (errorMessage) {
+  if (errorMessage && races.length === 0 && !isLoading) {
     return (
       <section className="page page--races" role="alert">
         <h1 className="page__title">Календарь стартов</h1>
@@ -109,6 +145,48 @@ export function RacesPage(): JSX.Element {
       <h1 className="page__title">Календарь стартов</h1>
       <p className="page__subtitle">Будущие и прошедшие старты в одном месте.</p>
 
+      <div className="races-filter" role="search" aria-label="Фильтр по дате">
+        <label className="races-filter__field">
+          <span className="races-filter__label">Год</span>
+          <select
+            className="races-filter__select"
+            value={yearFilter}
+            onChange={(event) => {
+              setYearFilter(event.target.value);
+            }}
+          >
+            <option value="">Все года</option>
+            {yearSelectOptions().map((y) => (
+              <option key={y} value={String(y)}>
+                {y}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className="races-filter__field">
+          <span className="races-filter__label">Месяц</span>
+          <select
+            className="races-filter__select"
+            value={monthFilter}
+            onChange={(event) => {
+              setMonthFilter(event.target.value);
+            }}
+          >
+            {MONTH_OPTIONS.map((opt) => (
+              <option key={opt.value || "all"} value={opt.value}>
+                {opt.label}
+              </option>
+            ))}
+          </select>
+        </label>
+      </div>
+
+      {isLoading ? (
+        <p className="page__subtitle" aria-busy="true">
+          Загружаем данные...
+        </p>
+      ) : null}
+
       <div className="race-lists">
         <RaceList title="Будущие" races={upcoming} />
         <RaceList title="Прошедшие" races={past} />

frontend/src/styles/global.css

@@ -144,6 +144,14 @@ a {
   font-size: var(--font-size-h2);
 }
 
+.dashboard-section__intro {
+  margin: calc(var(--space-2) * -1) 0 var(--space-4);
+  max-width: 42rem;
+  color: var(--color-text-muted);
+  font-size: var(--font-size-caption);
+  line-height: 1.5;
+}
+
 .dashboard-grid--pr {
   margin-top: 0;
 }
@@ -258,6 +266,74 @@ a {
   color: var(--color-success);
 }
 
+.race-card__status--registered {
+  background: #fff4e0;
+  color: #8a5a00;
+}
+
+.races-filter {
+  margin-top: var(--space-5);
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-4);
+  align-items: flex-end;
+}
+
+.races-filter__field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+  min-width: 10rem;
+}
+
+.races-filter__label {
+  font-size: var(--font-size-caption);
+  font-weight: 600;
+  color: var(--color-text-muted);
+}
+
+.races-filter__select {
+  font: inherit;
+  padding: var(--space-2) var(--space-3);
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--color-border);
+  background: var(--color-surface);
+  color: var(--color-text);
+}
+
+.pace-chart {
+  margin-top: var(--space-4);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+  background: #fcfdff;
+}
+
+.pace-chart__svg {
+  display: block;
+  width: 100%;
+  max-width: 560px;
+  height: auto;
+}
+
+.pace-chart__line {
+  stroke: var(--color-accent);
+  stroke-width: 1.5;
+  vector-effect: non-scaling-stroke;
+}
+
+.pace-chart__caption {
+  margin: var(--space-3) 0 0;
+  font-size: var(--font-size-caption);
+  color: var(--color-text-muted);
+}
+
+.pace-chart__empty {
+  margin: var(--space-2) 0 0;
+  color: var(--color-text-muted);
+  font-size: var(--font-size-body);
+}
+
 .page-link {
   margin-top: var(--space-4);
   display: inline-flex;