From f74ce6ed8891357915ffa694c3ab7db2d90c803b Mon Sep 17 00:00:00 2001 From: Anton Date: Tue, 7 Apr 2026 17:51:02 +0300 Subject: [PATCH] docs: fix README dev/production commands, update FRONTEND_PLAN status, remove broken links - README: separate dev (npm run dev) and production (npm run build && npm start) steps - FRONTEND_PLAN: mark backend-dependency-task as completed (finishPlace already in API) - Remove dead references to missing agent-frontend-ui-instructions.md from PLAN.md and FRONTEND_PLAN.md Made-with: Cursor --- FRONTEND_PLAN.md | 26 ++++++++++++-------------- PLAN.md | 2 +- README.md | 3 ++- 3 files changed, 15 insertions(+), 16 deletions(-) diff --git a/FRONTEND_PLAN.md b/FRONTEND_PLAN.md index c5298e1..b5ac813 100644 --- a/FRONTEND_PLAN.md +++ b/FRONTEND_PLAN.md @@ -1,7 +1,7 @@ --- name: Frontend implementation plan -overview: Собрать минималистичный frontend для календаря забегов по UI-инструкции, строго в рамках текущего API-контракта, с отдельной внешней задачей на недостающие backend-поля для completed-забегов. +overview: Собрать минималистичный frontend для календаря забегов по UI-инструкции, строго в рамках текущего API-контракта. todos: - id: frontend-structure @@ -20,8 +20,8 @@ status: completed content: Сделать блок PR и сравнение стартов с fallback для отсутствующего поля place status: completed - id: backend-dependency-task -content: Подготовить отдельную задачу для другого агента на расширение API полем place и последующую интеграцию во frontend -status: pending +content: "Расширение API полем finishPlace: миграция 002, маппер, DTO, фронтенд-интеграция — выполнено" +status: completed isProject: false --- @@ -30,7 +30,7 @@ isProject: false ## Исходные опоры -- UI и UX принципы берём строго из [d:\vaka.pro\calendar_run\agent-frontend-ui-instructions.md](d:/vaka.pro/calendar_run/agent-frontend-ui-instructions.md): минимализм, воздух, акцент на данных, спокойная палитра, быстрые сценарии. +- UI и UX принципы: минимализм, воздух, акцент на данных, спокойная палитра, быстрые сценарии (дизайн-токены в `frontend/src/styles/tokens.css`). - Продуктовые ограничения и структура экранов сверяем с [d:\vaka.pro\calendar_run\PLAN.md](d:/vaka.pro/calendar_run/PLAN.md). - Интеграционный контракт берём из [d:\vaka.pro\calendar_run\docs\backend-api-for-frontend.md](d:/vaka.pro/calendar_run/docs/backend-api-for-frontend.md). - Общий контекст запуска/окружения — [d:\vaka.pro\calendar_run\README.md](d:/vaka.pro/calendar_run/README.md) и [d:\vaka.pro\calendar_run\docs\backend.md](d:/vaka.pro/calendar_run/docs/backend.md). @@ -40,7 +40,7 @@ isProject: false - Только frontend + интеграция с текущим API. - Статус `зарегистрирован` трактуется как UI-вариант `planned` (без изменения backend-контракта). - Для completed-забегов обязательно показываем `темп`; считаем на фронте из `finishTime` и `distanceKm`. -- Для completed-забегов поле `место` обязательно по UX, но в API отсутствует: выделяем отдельную задачу другому агенту на расширение backend (`place`) и считаем это внешней зависимостью. +- Для completed-забегов поле `место` (`finishPlace`) доступно в API (миграция 002, маппер, DTO); фронтенд отображает его в карточке и таблице сравнения. ## Архитектура frontend @@ -61,14 +61,13 @@ isProject: false - Переключение `Будущие` / `Прошедшие`. - Карточка старта: `title`, `date`, `distanceKm`, статус-лейбл. - Карточка старта: - - Базовые поля + `finishTime`, вычисляемый `pace`, `notes`. - - `place` — вывод включается после backend-расширения. + - Базовые поля + `finishTime`, вычисляемый `pace`, `finishPlace`, `notes`. - PR блок: - Дистанции: 5K, 10K, 21.1, 42.2 (согласно UI-инструкции). - Расчёт по completed-забегам с валидным `finishTime`. - Сравнение стартов (ключевая фича): - - Таблица/карточки по годам с `time`, `pace`, `place`. - - До появления `place` в API — graceful-degradation: колонка в состоянии «нет данных». + - Таблица/карточки по годам с `time`, `pace`, `finishPlace`. + - Если `finishPlace` не заполнено — graceful-degradation: колонка в состоянии «нет данных». ## UX и визуальные требования @@ -78,10 +77,10 @@ isProject: false - Консистентные состояния загрузки/ошибок/пустых данных. - A11y-базис: фокус-стили, клавиатурная навигация, контраст, корректная разметка интерактивных элементов. -## Отдельная зависимая задача (другой агент) +## Зависимая задача (выполнена) -- Создать отдельную backend-задачу: добавить поле `place` в модель `Race` (миграция + API + документация контракта). -- После доставки backend-изменения: обновить frontend-типы, формы и блок сравнения, заменить placeholder на реальное значение. +- Поле `finishPlace` добавлено в модель `Race`: миграция `002_finish_place_and_registered_status.sql`, маппер `race.ts`, DTO, API-документация. +- Frontend-типы, карточка и блок сравнения используют `finishPlace`. ## Порядок реализации @@ -91,7 +90,6 @@ isProject: false 4. Реализовать карточку старта с вычислением `pace` на клиенте. 5. Реализовать PR и блок сравнения стартов с fallback для `place`. 6. Добавить состояния пустых данных/ошибок/загрузки и а11y-полировку. -7. Подготовить handoff-note с зависимостью на backend-задачу (`place`) и интеграционным чеклистом. ## Definition of Done для frontend @@ -99,4 +97,4 @@ isProject: false - API-интеграция работает по текущему контракту без локальных обходов хранилища. - `pace` считается корректно для completed-забегов. - `registered` не ломает модель: визуально интерпретируется в рамках `planned`. -- Для `place` есть явная внешняя задача и безопасный fallback в UI. \ No newline at end of file +- `finishPlace` интегрирован; при отсутствии значения — безопасный fallback в UI. \ No newline at end of file diff --git a/PLAN.md b/PLAN.md index d769140..a379f2d 100644 --- a/PLAN.md +++ b/PLAN.md @@ -55,7 +55,7 @@ PostgreSQL: `snake_case` столбцы, маппинг в `[backend/src/mappers - Маршруты: дашборд (`/`), список стартов (`/races`), карточка (`/races/:id`). - Дашборд: ближайший старт, последний результат, PR, сезон, PR по ключевым дистанциям, сравнение завершённых стартов, при необходимости — лёгкая визуализация прогресса. - Список: будущие / прошедшие; фильтрация по году и месяцу через API. -- Стили: BEM и дизайн-токены; ориентир по духу — `[agent-frontend-ui-instructions.md](agent-frontend-ui-instructions.md)`. +- Стили: BEM и дизайн-токены (см. `frontend/src/styles/tokens.css`). ## Критерии готовности текущей итерации diff --git a/README.md b/README.md index 086af1c..cf2f936 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ 2. Корень: `cp .env.example .env`, задайте `DB_*` (и при необходимости `CORS_ORIGIN`). 3. Postgres: из корня `docker compose up -d` (см. [`docker-compose.yml`](docker-compose.yml)) — в compose используются те же `DB_NAME`, `DB_USER`, `DB_PASSWORD` из `.env`. 4. `cd backend && npm run db:migrate && npm run seed` -5. `npm run build && npm run dev` +5. Dev-режим: `npm run dev` +6. Или production: `npm run build && npm start` Без PostgreSQL (только smoke API): в `.env` задайте `CALENDAR_RUN_MOCK_DB=1`; **`db:migrate` и `seed` с mock не использовать**.