Skip to content

Latest commit

 

History

History
981 lines (741 loc) · 51.1 KB

AGENTS.md

File metadata and controls

981 lines (741 loc) · 51.1 KB

AGENTS.md

1. Зачем этот файл

Этот документ фиксирует рабочий контекст по мобильному приложению assrep-mobile-app и задает единые правила для любых Codex-агентов, которые продолжают разработку.

Цель:

  • не терять контекст между сессиями;
  • поддерживать единый технический стиль;
  • не ломать уже стабилизированные роли/флоу;
  • быстрее доводить новые фичи до рабочего состояния.

2. Контекст проекта (актуально на 2026-02-27)

Проект: Expo + React Native + TypeScript + Zustand + i18n.

Ключевые принципы:

  • feature-first структура (src/features/*);
  • единый API-вход (src/shared/api/client.ts);
  • строгая типизация маршрутов (src/navigation/types.ts);
  • role-based UX (student / tutor / admin-tutor);
  • приоритет: рабочий student journey в mock-режиме и стабильная проверка smoke-набором.

Сейчас уже реализовано/зафиксировано:

  • mock-режим запуска через make local-mock-up и pnpm start:mock;
  • role-based конфиг нижних табов в src/navigation/mainTabsConfig.ts;
  • для student таба Finance нет (и не должен появляться);
  • smoke-покрытие критичных флоу student/tutor/admin;
  • quality gates в CI: lint + typecheck + test:smoke;
  • подготовленная база чатов (UI + store + mock API), включая graceful fallback, если backend не готов;
  • устранена часть техдолга с ролями и DEMO_* хардкодами в student-критичных экранах.

3. Обязательные продуктовые ограничения

  1. Student:
  • не получает экран финансов;
  • видит только логичный student-флоу: главная, предметы/репетиторы, календарь, чаты, профиль.
  1. Tutor:
  • имеет доступ к услугам, календарю, чатам, студентам/заявкам, финансам.
  1. Admin-tutor:
  • всё tutor + admin-поверхность в настройках.
  1. Любой новый экран/флоу должен сохранять role-aware поведение:
  • скрытие нерелевантных действий;
  • корректная навигация по ролям;
  • отсутствие лишних сущностей для student.

4. Текущая архитектура и правила модулей

4.1 UI и фичи

  • Экраны: src/features/<feature>/screens/*
  • Хуки фичи: src/features/<feature>/hooks/*
  • Переиспользуемые компоненты: src/shared/components/*

4.2 Состояние

  • Zustand в src/shared/state/*
  • Селекторы в src/shared/state/selectors.ts
  • Нельзя тянуть сырые данные напрямую в UI без явной роли/фильтрации.

4.3 API

  • Только через src/shared/api/client.ts (или mock-подмену через env).
  • Нельзя писать fetch напрямую в фичах/экранах.
  • Для любых новых endpoint-ов: типы + контракт + client-метод + тест.

4.4 Навигация

  • Константы маршрутов: src/shared/constants/routes.ts
  • Типы стеков/табов: src/navigation/types.ts
  • Новые экраны должны быть добавлены типобезопасно.

4.5 Локализация

  • Все тексты через t('...'), без хардкода строк в UI.

5. Что уже стабилизировано тестами

Основной smoke-набор закреплен в package.json -> test:smoke, включая:

  • mock API критичные сценарии;
  • role-based табы;
  • Home / Subjects / Tutors / TutorProfile / Slots / BookingConfirm / Review;
  • SignIn;
  • Chats;
  • Calendar / SlotDetails / SlotWizard;
  • TutorStudentDetails.

Подробности покрытия: docs/stabilization-sprint-1.md.

Правило:

  • если меняешь поведение в критичном флоу, обновляй соответствующий smoke-тест в этой цепочке.

6. Команды разработки

Базовые:

  • pnpm install
  • pnpm lint
  • pnpm typecheck
  • pnpm test
  • pnpm test:smoke

Запуск приложения:

  • make local-mock-up (предпочтительно для UI-итераций без backend)
  • pnpm start:mock
  • pnpm start:local

Окружения через Makefile:

  • make up-local
  • make up-stage
  • make up-prod

Важно:

  • перед mock-запуском останавливать старые Metro-процессы этого репо (частая причина "серого экрана").

7. CI и quality gates

Workflow: .github/workflows/android-debug-apk.yml.

Логика:

  • для push/pull_request на main: обязательный job quality-gates;
  • quality-gates включает:
    • pnpm lint
    • pnpm typecheck
    • pnpm test:smoke
  • сборка debug APK выполняется только после успешных quality gates и не запускается на PR.

Правило для агента:

  • локально прогонять минимум lint + typecheck + test:smoke перед коммитом.

8. Правила изменений в коде

  1. Не ломать текущий UX:
  • сначала сохранить поведение, потом улучшать структуру.
  1. Не плодить пасту:
  • повторяющуюся логику выносить в hooks/utils.
  • пример уже сделанного: общий useTutorNamesMap.
  1. Не вшивать демо-идентификаторы в критичных пользовательских операциях:
  • использовать useAuth().user?.id с fallback только для mock-совместимости.
  1. Держать типобезопасность:
  • не использовать any, кроме крайних случаев с комментариями-пояснениями.
  1. Менять аккуратно при грязном дереве:
  • в репозитории может одновременно работать другой агент;
  • не откатывать чужие изменения;
  • работать точечно по своим файлам.
  1. Комментарии в коде:
  • только там, где реально сложная логика;
  • избегать очевидных комментариев.

9. Правила по чат-фиче (backend еще не финализирован)

Текущее состояние:

  • UI и локальная логика чатов подготовлены;
  • mock API поддерживает thread/messages/send/read/ensure;
  • есть fallback-сообщение для случаев, когда backend endpoint не готов.

При развитии:

  • не завязывать UI на нестабильные backend-поля;
  • все backend-допущения изолировать в API-layer/store;
  • сохранять текущий UX при 404/chat_not_found/частичной недоступности API;
  • при появлении реального backend сначала обновить контракт/типы, потом экраны.

10. План приоритета на ближайшие итерации

  1. Дожать student journey до полностью логичного и связного UX:
  • экраны, состояния, пустые/ошибочные сценарии, навигационные переходы.
  1. Развивать chat UX поверх уже заготовленной базы:
  • предсказуемое поведение thread creation, загрузки истории, composer-state;
  • расширение smoke-тестов при добавлении новых сценариев.
  1. Убирать техдолг по тестам:
  • постепенно сокращать предупреждения react-test-renderer/act(...).
  1. Проводить селективный рефакторинг:
  • только с тестовой страховкой и без потери скорости разработки.

11. Definition of Done для каждой задачи

Задача считается завершенной, если:

  • код компилируется (typecheck зеленый);
  • линтер зеленый;
  • smoke-набор зеленый;
  • если изменен критичный флоу, тесты обновлены;
  • документация (README/docs/AGENTS) обновлена при изменении процесса/команд/архитектуры;
  • изменение не нарушает role-ограничения (особенно student без finance).

12. Формат коммитов и работа с git

Рекомендуемый стиль коммитов:

  • feat(student): ...
  • feat(chat): ...
  • fix(calendar): ...
  • test(smoke): ...
  • refactor(auth): ...
  • docs(agents): ...

Правила:

  • коммиты атомарные и логически цельные;
  • не смешивать в одном коммите рефакторинг и фичу без необходимости;
  • перед пушем прогонять quality-команды локально;
  • не использовать destructive git-команды без явного запроса пользователя.

13. Быстрый рабочий чеклист агента

Перед началом:

  • понять роль/флоу, который меняется;
  • проверить, есть ли уже smoke/юнит-тест на этот путь.

Во время:

  • править минимально необходимый набор файлов;
  • не трогать несвязанные участки;
  • следить за role-aware логикой.

Перед завершением:

  • pnpm lint
  • pnpm typecheck
  • pnpm test:smoke
  • при значимых изменениях: pnpm test
  • обновить документацию, если изменился процесс.

14. Главный принцип

Сначала рабочий пользовательский сценарий и предсказуемая логика, затем косметический рефакторинг.

Для этого проекта важнее стабильная доставка и проверяемость, чем "идеальная архитектура в вакууме".


15. Актуальный срез по мобильной разработке (добавлено 2026-02-27)

Ниже — фактический рабочий контекст, который появился в последних итерациях и критичен для продолжения работ без регрессий.

15.1 Слой API/контрактов сильно расширен под медиа

В src/shared/api/endpoints.ts добавлены endpoint-ы:

  • userAvatar, userAvatarUploadUrl, userAvatarMedia;
  • tutorPhotoMedia;
  • tutorServicePhotos, tutorServicePhotosUploadUrl, tutorServicePhotoById, tutorServicePhotoMedia.

В src/shared/api/types.ts добавлены/обновлены типы:

  • UserAvatar;
  • TutorPhoto (включая proxy_url, мета-поля);
  • TutorServicePhoto;
  • UploadUrlResponse.

В src/shared/api/client.ts добавлены методы:

  • avatar:
    • getUserAvatar
    • requestUserAvatarUploadUrl
    • upsertUserAvatar
    • deleteUserAvatar
  • tutor profile photos:
    • getTutorPhotos
    • requestTutorPhotoUploadUrl
    • confirmTutorPhotoUpload
    • updateTutorPhoto
    • deleteTutorPhoto
  • tutor service photos:
    • getTutorServicePhotos
    • requestTutorServicePhotoUploadUrl
    • confirmTutorServicePhotoUpload
    • updateTutorServicePhoto
    • deleteTutorServicePhoto

Также в ApiClient.request добавлен более строгий парсинг ошибок backend:

  • поддержка формата { error: { code, message, data } };
  • проброс status/code в Error (используется для UX-веток 409, 401 и т.д.);
  • отдельная нормализация user_not_found.

15.2 Единый media-utils слой

В src/shared/utils/media.ts реализован общий слой:

  • определение content_type (jpeg/png/webp);
  • генерация имени файла по MIME;
  • сортировка фото по position;
  • resolveMediaUrl с правилом proxy_url -> url;
  • автоматическое преобразование относительных proxy_url (/api/media/...) в абсолютные через API_BASE_URL;
  • uploadBinaryToStorage с timeout (45s) и ошибкой upload_timeout вместо бесконечного зависания.

Важно:

  • в UI/экранах нельзя напрямую собирать URL для картинок; нужно использовать resolveMediaUrl.

15.3 Хуки для изображений

Новые/обновленные хуки:

  • src/features/profile/hooks/useUserAvatar.ts:
    • полный flow avatar upload (upload-url -> PUT -> finalize -> sync);
    • состояние этапов загрузки (uploadStep) и прогресс;
    • обработка upload_timeout.
  • src/features/profile/hooks/useTutorPhotos.ts:
    • загрузка/замена/удаление фото профиля репетитора;
    • лимит 10;
    • обработка 409 + timeout.
  • src/features/services/hooks/useTutorServicePhotos.ts:
    • CRUD и reorder фото услуги;
    • лимит 5;
    • обработка 409 + timeout.
  • src/features/services/hooks/useServicePhotoPreviews.ts:
    • подгрузка первой миниатюры услуги (для спискового экрана услуг).

15.4 Что изменено в UI (текущее ожидаемое поведение)

  1. Профиль (src/features/profile/screens/ProfileScreen.tsx):
  • аватар использует useUserAvatar;
  • добавлен модальный индикатор этапов загрузки с прогресс-баром;
  • есть понятные тексты статусов загрузки.
  1. Настройки (src/features/settings/screens/SettingsScreen.tsx):
  • аватар тоже через useUserAvatar;
  • добавлен useFocusEffect с loadAvatar() для синхронизации после возврата со screen редактирования профиля.
  1. Список услуг (src/features/services/screens/ServicesScreen.tsx):
  • миниатюра услуги берется из первой service-photo;
  • формат миниатюры: горизонтальный 4/3;
  • название услуги отображается как primary/secondary (через getServiceCompactParts);
  • переключатель видимости — SVG глаз/глаз-off;
  • действие видимости подтверждается через HoldToConfirmModal;
  • кнопка создания услуги — минималистичный SVG +.
  1. Детали услуги (src/features/services/screens/ServiceDetailsScreen.tsx):
  • слайдер показывает реальные service photos (не заглушки);
  • если фото нет, показывается placeholder;
  • редактирование описания вынесено в отдельный modal-экран ввода;
  • лимит длины описания: 500 символов;
  • удаление услуги через HoldToConfirmModal.

15.5 Локализация (новые ключи, которые уже используются)

Добавлены ключи в src/shared/config/i18n.ts:

  • servicePhotosLimit
  • avatarUploadTitle
  • avatarUploadPreparing
  • avatarUploadUploading
  • avatarUploadFinalizing
  • avatarUploadSyncing
  • photoUploadTimeoutHint

Правило:

  • при добавлении новых состояний загрузки/ошибок обязательно добавлять ключи в en и ru.

16. Критичный runtime-контекст по загрузке фото (core + mobile)

16.1 Почему загрузка может "висеть" без явной ошибки

Сценарий:

  1. mobile успешно получает upload_url (POST .../upload-url);
  2. зависает на PUT upload_url;
  3. finalize (PUT /avatar или POST /photos) не вызывается;
  4. в backend логах видно только шаг 1.

Типичная причина:

  • неверный S3_PRESIGN_PUBLIC_ENDPOINT относительно типа клиента, который выполняет PUT.

16.2 Матрица S3_PRESIGN_PUBLIC_ENDPOINT

Нужно указывать адрес, доступный устройству/эмулятору, где крутится мобильный клиент:

  • Android emulator (AOSP/Studio):
    • http://10.0.2.2:4566
  • iOS simulator / curl с хоста:
    • http://localhost:4566
  • Физический телефон в Wi-Fi:
    • http://<LAN-IP-хоста-с-Localstack>:4566
    • пример: http://192.168.1.130:4566

Важно:

  • это IP хоста с backend/localstack, не IP телефона.
  • при смене сети/роутера LAN-IP хоста меняется -> env нужно обновить и перезапустить контейнеры.

16.3 Минимальный restart после смены env в core

Из ../core:

  • docker-compose up -d --force-recreate backend worker beat

Проверка внутри backend-контейнера:

  • docker-compose exec -T backend python -c "from app.settings import settings; print(settings.S3_PRESIGN_PUBLIC_ENDPOINT)"

17. Авторизация и деградация при недоступности backend

Актуальная модель:

  • периодическая верификация сессии включена в src/app.tsx через AUTH_VERIFY_INTERVAL_MS;
  • authStore.restore():
    • при invalid session (401, user_not_found, invalid token и т.д.) делает signOut;
    • при transient-ошибках (timeout/network) не деавторизует, оставляет локальную сессию.
  • ServerStatusBanner показывает недоступность backend поверх UI.

Это соответствует правилу:

  • деавторизация только при реально невалидной сессии;
  • при сетевых/временных ошибках показывать плашку, но не выбрасывать пользователя.

18. Что обязательно проверить руками после любых изменений в media

  1. Avatar flow:
  • профиль: выбрать фото -> увидеть пошаговый статус загрузки;
  • после завершения аватар виден и в Profile, и в Settings.
  1. Tutor profile photos:
  • добавить фото, удалить фото, reorder;
  • обработка лимита 10 (409 + UX-сообщение).
  1. Tutor service photos:
  • добавить фото услуги, удалить, reorder;
  • лимит 5;
  • превью в списке услуг обновляется после refresh.
  1. URL-режимы:
  • проверить, что proxy_url и относительные media-path корректно рендерятся.
  1. Ошибки:
  • принудительно воспроизвести timeout/недоступность storage и убедиться, что есть понятное сообщение пользователю.

19. Тестовый минимум для задач, затрагивающих текущие изменения

Если трогается media/API/auth/session/UI профиля/услуг:

  • pnpm lint
  • pnpm typecheck
  • pnpm test:smoke
  • минимум дополнительно:
    • pnpm vitest run src/shared/api/client.test.ts src/shared/api/client.methods.test.ts src/shared/api/endpoints.test.ts
    • pnpm vitest run src/shared/utils/media.test.ts src/shared/utils/apiError.test.ts

Если трогается core-часть presign/storage:

  • в ../core: poetry run pytest tests/clients/test_s3_client.py -q

20. Важные анти-паттерны (на основе последних инцидентов)

  1. Нельзя полагаться только на успешный upload-url:
  • шаг 1 не гарантирует, что бинарник реально залился и запись финализировалась.
  1. Нельзя держать бесконечный upload без timeout:
  • пользователь видит "зависло" и не понимает причину.
  1. Нельзя отображать изображения без resolveMediaUrl:
  • относительные proxy_url ломают рендер в RN при прямом использовании.
  1. Нельзя забывать re-fetch после CRUD операций с фото:
  • UI легко уходит в рассинхрон.
  1. Нельзя использовать deprecated ImagePicker.MediaTypeOptions:
  • использовать mediaTypes: 'images' или новый API media type.

21. Финансовая витрина (analytics) — текущий рабочий срез

Этот блок фиксирует фактическое состояние экрана финансов и контрактов analytics, чтобы новые итерации не возвращались к устаревшему контексту.

21.1 Role-aware доступ к финансам

  • Источник правды по табам: src/navigation/mainTabsConfig.ts.
  • Finance таб присутствует только у tutor.
  • Для student таба Finance нет, и это закреплено тестом src/navigation/mainTabsConfig.test.ts.
  • Даже при прямом открытии FinanceScreen на уровне экрана есть guard: для не-tutor выводится sectionInProgress без загрузки витрины.

21.2 API-контракт analytics в мобильном слое

В src/shared/api/endpoints.ts и src/shared/api/client.ts используются 4 endpoint-а:

  • GET /tutors/{tutor_id}/analytics/summary
  • GET /tutors/{tutor_id}/analytics/services
  • GET /tutors/{tutor_id}/analytics/timeseries
  • GET /tutors/{tutor_id}/analytics/price-history

В src/shared/api/types.ts зафиксированы типы:

  • TutorAnalyticsSummary
  • TutorAnalyticsServiceBreakdown
  • TutorAnalyticsTimeseries + TutorAnalyticsTimeseriesPoint
  • TutorAnalyticsPriceHistory (+ service/trial history item types)

Критично:

  • поле lessons_rescheduled уже добавлено в:
    • TutorAnalyticsSummary
    • TutorAnalyticsTimeseriesPoint
  • при любых будущих изменениях backend-схемы analytics нужно синхронно обновлять эти типы.

21.3 Что сейчас делает useTutorFinance

Файл: src/features/finance/hooks/useTutorFinance.ts.

Поведение:

  • принимает tutorId, periodDays, enabled;
  • строит период dateFrom/dateTo по локальному времени устройства;
  • грузит витрины параллельно (Promise.all) для 4 endpoint-ов;
  • выбирает granularity:
    • day для 7/30 дней,
    • week для 90 дней (условие periodDays > 60);
  • использует автообновление по BACKGROUND_REFRESH_MS с silent-режимом;
  • если backend вернул user_not_found -> вызывает signOut (через authStore);
  • защищен от race-condition через requestIdRef (только последний запрос пишет в state).

21.4 Что сейчас показывает FinanceScreen

Файл: src/features/finance/screens/FinanceScreen.tsx.

Текущее UI-содержимое:

  • фильтры периода: 7 / 30 / 90 дней;
  • KPI-карточки:
    • planned revenue
    • paid revenue
    • paid lessons
    • average check
    • cancelled lessons
    • rescheduled lessons
    • payment rate
  • блок динамики (timeseries):
    • planned revenue
    • paid revenue
    • rescheduled lessons
  • разбивка по услугам (planned/paid revenue + paid/total lessons);
  • история изменения цен:
    • service price history
    • trial price history
  • корректные состояния:
    • initial loading
    • pull-to-refresh
    • error + retry
    • empty state.

Локализация:

  • ключи finance вынесены в src/shared/config/i18n.ts (en + ru), включая financeRescheduledLessons.

21.5 Mock-совместимость analytics

В src/shared/api/mockClient.ts реализованы mock-версии analytics endpoint-ов.

Текущее состояние mock:

  • summary.lessons_rescheduled вычисляется;
  • в timeseries поле lessons_rescheduled присутствует в контракте, но сейчас не инкрементится в bucket-агрегации (по умолчанию остается 0).

Практический вывод:

  • если в mock-режиме переносы в timeseries выглядят нулями, это ожидаемо до доработки mock-агрегации.
  • не считать это автоматически багом backend.

22. Известные ограничения и риски по Finance

  1. Нет отдельного smoke-теста на FinanceScreen.
  • Сейчас контракт покрывается API-тестами (endpoints/client.methods), но UI-поведение Finance не зафиксировано smoke-набором.
  1. FinanceStack использует строковый route-name "Finance" в src/navigation/index.tsx.
  • Это не критично в текущем состоянии, но при будущем рефакторинге лучше выровнять с ROUTES, чтобы не терять типобезопасность.
  1. Форматирование денег зависит от currency из summary.
  • fallback в UI: RUB, если поле не пришло.
  • для нестандартных кодов валюты Intl может fallback-нуть в plain number.
  1. История цен объединяет service и trial в одну ленту в UI.
  • сортировка по changed_at desc;
  • источник и actor пока не выводятся.

23. Правило синхронизации при изменении analytics backend

Если backend меняет любые поля в analytics (summary/services/timeseries/price-history), изменения считаются завершенными только после синхронизации всех уровней:

  1. Swagger/схемы в core.
  2. src/shared/api/types.ts.
  3. src/shared/api/client.ts (query/body/response).
  4. src/shared/api/mockClient.ts (чтобы mock-режим не расходился с контрактом).
  5. src/features/finance/hooks/useTutorFinance.ts (если меняется логика загрузки/фильтрации).
  6. src/features/finance/screens/FinanceScreen.tsx (UI + empty/error states).
  7. src/shared/config/i18n.ts (en + ru ключи).
  8. Тесты:
  • src/shared/api/endpoints.test.ts
  • src/shared/api/client.methods.test.ts
  • при необходимости smoke/UI тесты.
  1. Обновление контекста в AGENTS.md.

Если хоть один пункт пропущен, задача считается частично завершенной.


24. Проверки для задач, затрагивающих Finance/analytics

Минимум:

  • pnpm lint
  • pnpm typecheck
  • pnpm test:smoke

Рекомендуемый прицельный прогон:

  • pnpm vitest run src/navigation/mainTabsConfig.test.ts
  • pnpm vitest run src/shared/api/endpoints.test.ts src/shared/api/client.methods.test.ts
  • pnpm vitest run src/shared/api/mockClient.smoke.test.ts

Если менялись форматирование/тексты finance:

  • проверить en и ru локали руками на экране.

Ручной sanity для finance:

  1. Tutor role:
  • таб Finance виден;
  • данные грузятся;
  • периоды 7/30/90 переключаются;
  • pull-to-refresh работает.
  1. Student role:
  • таба Finance нет.
  1. Ошибки сети:
  • отображается ошибка и доступен Retry.
  1. Mock mode:
  • экран открывается и не падает при частичной пустоте данных.

25. Профиль и параметры: фактический UX-контракт (добавлено 2026-02-27, поздняя итерация)

Ниже фиксируется именно текущий продуктовый договор по экрану профиля/настроек, который появился после серии UI-итераций.

25.1 Информационная архитектура Settings/Profile

Текущий SettingsStack:

  • SETTINGS_STACK (SettingsScreen) — корневой экран профиля;
  • APP_SETTINGS (AppSettingsScreen) — системные настройки (тема, роль, переход к уведомлениям);
  • NOTIFICATION_SETTINGS (NotificationSettingsScreen);
  • BLACKLIST (BlacklistScreen);
  • FEEDBACK (FeedbackScreen);
  • RELEASE_NOTES (ReleaseNotesScreen);
  • ADMIN (AdminScreen, только при user.is_admin);
  • PROFILE (ProfileScreen) — отдельный экран редактирования профиля.

Навигационный принцип:

  • в шапке SettingsScreen кнопка ведет в AppSettingsScreen;
  • в шапке AppSettingsScreen есть явная кнопка "назад в профиль" (переход в SETTINGS_STACK);
  • редактирование персональных полей вынесено в PROFILE.

25.2 Минимальный состав полей профиля (MVP)

На экране ProfileScreen пользователь редактирует только:

  • Имя (name);
  • Фамилия (lastName);
  • Телефон (phone);
  • Email (email).

Важно:

  • расширенные tutor-поля пока не показываются в UI;
  • они остаются в profileStore как задел на постепенное включение;
  • решение принято специально, чтобы не перегружать пользователя на первом экране профиля.

25.3 Контракт по фото профиля

Актуальная модель:

  • в профиле используется одна фотография профиля (avatar), а не галерея;
  • фото услуги — отдельная сущность и редактируются только в флоу услуг;
  • в ProfileScreen сверху расположен центрированный avatar/placeholder + маленький badge с карандашом;
  • текстовые CTA вида "Фотографии / Добавить фото" в профиле не используются.

Поведение по тапу на аватар:

  • если фото отсутствует: открыть системный picker и загрузить;
  • если фото уже есть: показать confirm-диалог замены и при подтверждении загрузить новое фото;
  • используется useUserAvatar (upload-url -> PUT -> finalize -> sync) с индикацией этапов загрузки.

25.4 Стиль и визуальный язык экрана профиля/настроек

Зафиксированные UI-решения:

  • разделение контента в первую очередь линиями-разделителями и секциями, а не "тяжелыми карточками";
  • для шапок использовать нижнюю линию на всю ширину (как на Services/Calendar);
  • визуальная иерархия ближе к популярным маркетплейс-паттернам (Avito-like), а не iOS-копии;
  • в форме профиля поля расположены в линейном вертикальном списке с divider между строками;
  • блок фото внизу профиля отсутствует.

25.5 Ролевое поведение в профиле/параметрах

  • SettingsScreen использует effectiveRole из useAuth для подписи роли (Student/Tutor);
  • блок Admin в настройках отображается только при user.is_admin;
  • редактирование профиля (имя/фамилия/телефон/email/avatar) доступно одинаково для student и tutor;
  • tutor-галерея профиля сейчас не экспонируется через UI (см. секцию 28).

26. Технический срез по реализации профиля/настроек

26.1 Хуки и store

  • src/features/auth/hooks/useAuth.ts
    • вычисляет effectiveRole + флаги isTutor/isStudent/isAdmin;
    • при login/register/restore синхронизирует профиль в store;
    • full_name разбивается на name + lastName через splitFullName.
  • src/shared/state/profileStore.ts
    • содержит name, lastName, phone, email, role;
    • содержит расширенный tutor-блок (пока скрыт из UI);
    • предоставляет set/update-методы для всех полей.
  • src/features/profile/hooks/useProfile.ts
    • единая точка доступа UI к данным профиля;
    • включает update-методы для name/lastName/phone/email и tutor-полей.
  • src/features/profile/hooks/useUserAvatar.ts
    • хранит avatar, avatarUrl, uploadStep, uploadProgress;
    • обрабатывает timeout (upload_timeout) и дружелюбный текст ошибки.

26.2 Экраны

  • src/features/settings/screens/SettingsScreen.tsx
    • профильный summary-блок (avatar + ФИО + телефон + роль);
    • useFocusEffect вызывает loadAvatar() при возврате на экран;
    • точки входа: edit profile, notification settings, feedback, release notes, blacklist, admin.
  • src/features/settings/screens/AppSettingsScreen.tsx
    • переключение темы (system/light/dark);
    • переключение роли (student/tutor);
    • back action в SETTINGS_STACK.
  • src/features/profile/screens/ProfileScreen.tsx
    • центрированный avatar + badge-pencil;
    • линейная форма из 4 полей;
    • modal-индикатор этапов загрузки аватара.
  • src/features/settings/screens/NotificationSettingsScreen.tsx
    • хранит retryIntervalMinutes/maxAttempts в settingsStore;
    • валидирует только числовой ввод.
  • src/features/settings/screens/BlacklistScreen.tsx
    • отображение локального blacklist из settingsStore + remove action.

26.3 Локализация

Для текущего профиля/медиа уже используются ключи:

  • lastNameLabel;
  • changePhotoAction, changePhotoTitle, changePhotoPrompt;
  • avatarUploadTitle, avatarUploadPreparing, avatarUploadUploading, avatarUploadFinalizing, avatarUploadSyncing;
  • photoUploadTimeoutHint.

Правило:

  • при добавлении нового upload-step или нового alert-сценария обновлять обе локали (en + ru) синхронно.

27. Тестовый минимум для изменений в Profile/Settings/Media

Если задача затрагивает профиль, настройки, avatar/media utils, auth sync:

  • pnpm lint
  • pnpm typecheck
  • pnpm test:smoke

Рекомендуемый прицельный прогон:

  • pnpm vitest run src/shared/state/profileStore.test.ts src/shared/state/authStore.test.ts
  • pnpm vitest run src/shared/utils/media.test.ts src/shared/utils/apiError.test.ts
  • pnpm vitest run src/shared/api/client.test.ts src/shared/api/client.methods.test.ts src/shared/api/endpoints.test.ts

Ручной sanity после изменений:

  1. Открыть ProfileScreen и проверить поля name/lastName/phone/email.
  2. Тап по avatar без фото -> picker -> успешная загрузка и отрисовка.
  3. Тап по avatar с фото -> confirm -> замена фото.
  4. Проверить upload modal со step-текстами и прогресс-баром.
  5. Вернуться в SettingsScreen и убедиться, что avatar синхронизировался.
  6. Проверить AppSettingsScreen: back в профиль, theme switch, role switch.

28. Текущие ограничения и техдолг по профилю/медиа

  1. useTutorPhotos остается в кодовой базе как задел под tutor-gallery, но в текущем UX профиля не подключен.
  • Это осознанно: в профиле 1 avatar, фото для контента уехали в услуги.
  1. В profileStore есть много tutor-полей, которые не отражаются в текущем UI.
  • Это не баг, а staged rollout.
  • При открытии новых полей включать их порционно и с UX-проверкой на перегрузку формы.
  1. Для SettingsScreen/ProfileScreen нет выделенного smoke-теста в test:smoke цепочке.
  • Пока поведение косвенно защищено unit/API тестами и ручным sanity.
  • При следующем цикле стабилизации желательно добавить отдельные smoke-тесты этих экранов.
  1. В навигации FinanceStack все еще использует строковый route-name "Finance" внутри index.tsx.
  • Это известное ограничение из предыдущих секций и не должно быть случайно размножено в новых стеках.

29. Календарь и слоты: фактический срез (добавлено 2026-02-27, поздняя итерация)

Этот блок фиксирует текущее состояние tutor-календаря после серии UX-правок, чтобы следующие агенты не откатывали уже согласованное поведение.

29.1 Что считать источником правды по calendar UX

Основные файлы:

  • src/features/calendar/screens/CalendarScreen.tsx
  • src/features/calendar/screens/SlotWizardScreen.tsx
  • src/features/calendar/screens/SlotDetailsScreen.tsx
  • src/features/calendar/hooks/useTutorSlots.ts
  • src/shared/state/tutorSlotsStore.ts
  • src/shared/api/client.ts
  • src/shared/api/types.ts
  • src/shared/config/i18n.ts

Принцип:

  • если поведение календаря обсуждается, смотреть в первую очередь эти файлы, а не старые обсуждения/скриншоты.

29.2 Контракт по шапке и структуре экрана календаря

Текущее согласованное поведение CalendarScreen:

  • в хедере экрана текст строго Календарь;
  • справа в хедере компактная кнопка + для создания слота;
  • большая кнопка Создать окно в теле экрана не используется;
  • ниже хедера идет переключатель Планер / Список слотов;
  • между Планер/Список и Месяц/Неделя/День выводится период (увеличенный и более контрастный текст);
  • заголовок стека (workWindowsTitle) локализован как Calendar / Календарь.

29.3 Контракт по planner-виду (Google/Outlook-подобная логика)

Для tutor planner закреплено:

  • режимы: month / week / day;
  • сохранен horizontal swipe влево/вправо через PagerView в day/week режимах;
  • сохранены анимации перехода week<->day (react-native-reanimated);
  • в day/week только сетка часов вертикально скроллится;
  • верхние элементы (дни недели, числа, контролы) остаются фиксированными;
  • в month-виде под числом даты НЕ показывается дополнительный счетчик количеством;
  • на day/week-grid есть красная линия текущего времени;
  • при первом открытии planner day/week сетка автоматически прокручивается к зоне текущего времени;
  • по кнопке Сегодня происходит переход на текущую дату и докрутка к текущему времени;
  • tap по сетке часов открывает wizard создания слота на ближайший 15-мин интервал;
  • рабочий визуальный диапазон сетки сейчас 07:00–22:00.

29.4 Контракт по статусным счетчикам в planner

Счетчики над grid:

  • в одну строку с горизонтальным скроллом;
  • статусы: all/free/booked_pending/scheduled/cancelled;
  • по тапу на счетчик включается focus этого статуса;
  • в day/week выделяются только слоты выбранного статуса (остальные приглушаются);
  • в month режиме дни без слотов выбранного статуса визуально приглушаются.

29.5 Контракт по list-виду (Список слотов)

Список слотов должен оставаться структурно таким:

  • фильтр по статусу;
  • фильтр по услуге;
  • фильтр по ученику;
  • карточки слотов с переходом в детали.

Критично по фильтру услуг:

  • список услуг в фильтре строится из tutorServices (созданные у репетитора);
  • дополнительно включаются service_id из текущих слотов как fallback (чтобы не потерять фильтрацию исторических/нестандартных записей).

29.6 Контракт по wizard создания/редактирования слота

SlotWizardScreen сейчас сознательно переработан под более прикладной UX:

  • услуга выбирается НЕ через дерево категорий;
  • услуга выбирается из реально созданных услуг репетитора (useTutorServices);
  • при выборе услуги цена/час автоподставляется из tutor-service и остается редактируемой;
  • дата и время задаются отдельно через picker;
  • длительность: пресеты + ручной ввод;
  • есть блок сводки (slotSummaryTitle) на экране;
  • валидации перед submit:
    • выбранная услуга;
    • валидная дата/время;
    • start_at строго в будущем;
    • duration > 0;
    • price > 0.

Критичное изменение подтверждения:

  • финальное подтверждение создания/сохранения слота больше НЕ через Alert confirm;
  • используется базовый HoldToConfirmModal (единый паттерн проекта);
  • hold-label-и:
    • holdToCreateWindowAction
    • holdToSaveWindowAction.

29.7 Контракт по деталям слота

SlotDetailsScreen поддерживает:

  • загрузку актуального слота + истории статусов (getSlot + getSlotHistory);
  • fallback на данные из store, если direct-load не удался;
  • отображение status/time/duration/price/total/paid;
  • показ cancel_reason, если есть;
  • действия по статусам:
    • free: редактировать / отменить / удалить;
    • booked_pending: подтвердить / отклонить / отменить;
    • scheduled: отменить;
  • cancel/delete выполняются с вводом причины в modal.

29.8 API и store-контракты под календарь (актуально)

В src/shared/api/client.ts для слотов поддерживается:

  • listSlots с фильтрами serviceId, studentId, status, startFrom, startTo, пагинацией;
  • getSlot(slotId);
  • getSlotHistory(slotId);
  • confirmSlot(slotId, tutorId) (tutorId передается в body);
  • declineSlot(slotId, tutorId) (tutorId передается в body);
  • cancelSlot({ slotId, actorId, reason? });
  • deleteSlot(slotId, actorId, reason?).

В src/shared/api/types.ts расширения:

  • Slot содержит cancel_reason, cancelled_by и служебные timestamps;
  • добавлен SlotStatusHistory.

В tutorSlotsStore и useTutorSlots:

  • load/refresh/silent-refresh принимают serviceId и studentId.

29.9 Локализация, связанная с календарем

Ключевые изменения i18n:

  • workWindowsTitle -> Calendar / Календарь;
  • добавлены ключи для hold-подтверждения:
    • holdToCreateWindowAction
    • holdToSaveWindowAction.

Правило:

  • любые новые calendar/slot тексты обязательно дублировать в en и ru.

29.10 Что уже проверялось в последних итерациях

В последних calendar-итерациях прогонялись:

  • pnpm typecheck;
  • прицельно pnpm vitest run src/shared/api/client.methods.test.ts src/shared/state/tutorSlotsStore.test.ts.

Важно:

  • перед merge календарных изменений стандарт остается прежним: lint + typecheck + test:smoke.

29.11 Известные риски/ограничения calendar блока

  1. Calendar UX сейчас сфокусирован на tutor use-cases.
  • student use-cases (избранные, мои уроки) требуют отдельной продуктовой доработки, чтобы не смешивать роли.
  1. Визуальные правки calendar легко ломают sticky-иерархию.
  • любое изменение layout day/week сначала проверять руками на реальном скролле сетки.
  1. Любые изменения в SlotWizard подтверждении не должны уводить проект обратно к разным шаблонам confirm.
  • приоритет: единый HoldToConfirmModal для финальных подтверждений критичных действий.
  1. При правках фильтров списка слотов нельзя возвращаться к источнику только из slots.
  • источник услуг в фильтре: сначала tutorServices, затем fallback слотами.

30. Быстрый чеклист для задач по Calendar/Slots

Перед началом:

  • определить, меняется planner, list, wizard или details;
  • проверить role-impact (student/tutor/admin-tutor);
  • проверить, не ломает ли изменение контракт section 29.

Во время:

  • держать стабильным PagerView + animated day/week;
  • не трогать лишние фичи за пределами calendar/slots;
  • все API-вызовы делать через client.ts, без прямого fetch.

Перед завершением:

  • pnpm lint
  • pnpm typecheck
  • pnpm test:smoke
  • при правках slot API/store дополнительно:
    • pnpm vitest run src/shared/api/client.methods.test.ts src/shared/state/tutorSlotsStore.test.ts

Ручной sanity (минимум):

  1. Planner: month/week/day переключаются, swipe работает.
  2. В day/week шапка фиксирована, скроллится только сетка часов.
  3. Автопрокрутка при входе ведет к текущему времени (красная линия в зоне видимости).
  4. Статусные счетчики горизонтально скроллятся и подсвечивают соответствующие слоты.
  5. List filters: статус/услуга/ученик работают, услуги берутся из tutor-services.
  6. SlotWizard: выбор услуги только из услуг репетитора, hold-confirm работает.
  7. SlotDetails: confirm/decline/cancel/delete и история статусов работают без падений.