Qadam Roadmap
← Назад к библиотеке
проектdocs/frontend/frontend-mvp-cto-backend-handoff-2026-04-14.md

Handoff для frontend по MVP-изменениям CTO

Обновлён 15 апр. 2026 г., 10:05 · 0 комментариев

ИсходникСкачать

Handoff для frontend по MVP-изменениям CTO

Паспорт документа

  • Статус документа: working reference

  • Актуально на: 14 апреля 2026 года

  • Владелец: backend/platform-команда, совместно с frontend-командой

  • Пересмотр: при изменении MVP-контрактов buyer/staff/leads/public seller profile

  • Область применения: handoff backend-контрактов qadam-core для команды qadam-web по пакету CTO MVP changes

  • Связанные документы:

  • Статус: ready for frontend

  • Актуально на: 14 апреля 2026

  • Репозиторий: qadam-core

  • Источник истины по контракту: apps/api/openapi/openapi.json

Что изменилось в backend

Этот пакет меняет backend-контракт под новый MVP. Фронту нужно обновить формы, маршруты и клиентские DTO по этим endpoint-изменениям, не придумывая временные адаптеры поверх старого контракта.

Главные изменения:

  • buyer child model переведена с age/birthYear на birthdate в формате ДД.ММ.ГГГГ
  • lead creation больше не принимает контактные поля и требует childId
  • seller staff creation/update больше не работает через свободные поля роли и блокировки
  • teacher specialization теперь должна идти через subjectId из каталога
  • public seller profile больше не отдаёт контакты и соцсети
  • item с priceFrom=0 или priceTo=0 больше не считается валидным для MVP

1. Buyer registration и buyer profile

POST /api/v1/auth/register/buyer

Phone validation:

  • телефон валидируется на backend
  • нужно использовать тот же формат, что уже применялся во flow восстановления пароля

Изменение child payload:

  • было:
    • age
  • стало:
    • birthdate

Формат:

  • birthdate: строка в формате ДД.ММ.ГГГГ

Для buyerType=STUDENT:

  • вместо birthYear теперь передаётся birthdate

Пример:

{
  "firstName": "Ali",
  "lastName": "Valiyev",
  "phone": "+998901234567",
  "password": "StrongPass123",
  "buyerType": "PARENT",
  "children": [
    {
      "firstName": "Sara",
      "lastName": "Valiyeva",
      "birthdate": "14.09.2015",
      "schoolGrade": 4,
      "subjectIds": ["9c4f7c80-1111-4b55-9000-aaaaaaaaaaaa"]
    }
  ]
}

POST /api/v1/me/profile

PATCH /api/v1/me/profile

PUT /api/v1/me/profile

Если фронт создаёт или обновляет student-buyer профиль:

  • больше не использовать birthYear
  • использовать birthdate

GET /api/v1/me/profile

Изменение response:

  • в профиле ребёнка больше нет age
  • в student/buyer профиле больше нет birthYear

Теперь frontend получает:

  • children[].birthdate
  • profile.birthdate

Формат ответа:

{
  "profile": {
    "buyerId": "uuid",
    "buyerType": "PARENT",
    "firstName": "Ali",
    "lastName": "Valiyev",
    "phone": "+998901234567",
    "email": null,
    "accountStatus": "ACTIVE",
    "children": [
      {
        "studentId": "uuid",
        "firstName": "Sara",
        "lastName": "Valiyeva",
        "birthdate": "14.09.2015",
        "schoolGrade": 4,
        "interests": []
      }
    ],
    "birthdate": null,
    "schoolGrade": null,
    "interests": null
  }
}

GET /api/v1/me/children

POST /api/v1/me/children

PATCH /api/v1/me/children/:studentId

Изменение child contract:

  • было:
    • age
  • стало:
    • birthdate

Фронту нужно:

  • заменить возраст на дату рождения
  • использовать формат ДД.ММ.ГГГГ
  • для children management больше не строить UI вокруг числового возраста

2. Lead submission

POST /api/v1/leads

Lead creation теперь доступен только авторизованному buyer. Гостевой сценарий на backend не поддерживается.

Изменение request body:

  • было:
    • itemId
    • type
    • name
    • phone
    • email
    • comment
    • source
  • стало:
    • itemId
    • childId
    • comment
    • source

Пример:

{
  "itemId": "d1f0fd0c-1111-4ab2-8f00-aaaaaaaaaaaa",
  "childId": "c2d9b7d0-2222-4781-8f00-bbbbbbbbbbbb",
  "comment": "Интересует расписание",
  "source": "item_page"
}

Что должен сделать frontend:

  • убрать guest lead submission flow
  • убрать поля контактов из формы лида
  • убрать переключатель типа заявки
  • передавать выбранного ребёнка через childId
  • если у buyer несколько детей, давать явный выбор

GET /api/v1/me/leads

GET /api/v1/seller/leads

В lead response добавлен child.

Пример структуры:

{
  "id": "uuid",
  "status": "CREATED",
  "type": "BUY",
  "itemId": "uuid",
  "child": {
    "id": "uuid",
    "firstName": "Sara",
    "lastName": "Valiyeva",
    "birthdate": "14.09.2015",
    "class": 4
  }
}

PUT /api/v1/seller/leads/:id/status

Изменение статусов:

  • backend больше не позволяет вручную ставить CREATED
  • допустимые входные значения:
    • CONTACTED
    • ENROLLED
    • REJECTED

Что должен сделать frontend:

  • убрать new/created из selectable target statuses
  • разрешать seller менять lead в любой из трёх рабочих статусов

3. Seller staff / teachers

POST /api/v1/seller/staff

Изменение request body:

  • role больше не передаётся
  • photoUrl обязателен
  • subjectId обязателен

Новый request:

{
  "email": "teacher@example.com",
  "phone": "+998901234567",
  "password": "StrongPass123",
  "name": "Dilshod Karimov",
  "photoUrl": "https://cdn.example.com/teachers/dilshod.jpg",
  "subjectId": "7f14be6d-3333-4d87-8f00-cccccccccccc"
}

Правила:

  • backend создаёт такого сотрудника как teacher
  • свободный выбор роли больше не поддерживается
  • поле специализации должно идти через subjectId

PUT /api/v1/seller/staff/:id

Изменение request body:

  • можно обновлять только:
    • name
    • phone
    • email
    • photoUrl
    • subjectId

Больше нельзя обновлять через этот endpoint:

  • role
  • isActive

GET /api/v1/seller/staff

GET /api/v1/seller/staff/:id

Изменение response:

  • staff member теперь включает photoUrl
  • staff member теперь включает subject
  • isActive больше не часть frontend-контракта этого списка

Пример:

{
  "staff": {
    "id": "uuid",
    "name": "Dilshod Karimov",
    "phone": "+998901234567",
    "email": "teacher@example.com",
    "photoUrl": "https://cdn.example.com/teachers/dilshod.jpg",
    "subject": {
      "id": "uuid",
      "name": "Английский",
      "groupId": "languages",
      "groupName": "Языки"
    },
    "role": "teacher",
    "accountId": "uuid"
  }
}

Что должен сделать frontend:

  • убрать Seller Manager
  • убрать block/unblock staff action
  • для teacher specialization строить выбор по каталогу

4. Catalog tree для teacher specialization

GET /api/v1/catalog/subjects

Этот endpoint теперь критичен для формы преподавателя.

Использование:

  • фронт должен брать specialization не из ручного текста
  • фронт должен строить выбор по инфомодели каталога
  • использовать groupId и groupName для группировки предметов в UI

Практически:

  • category/group: groupName
  • subcategory/item: name
  • в backend отправляется subjectId

5. Public seller profile

GET /api/v1/sellers/:id

Из публичного seller profile убраны:

  • phone
  • email
  • websiteUrl
  • instagramUrl
  • telegramChannel

Также эти поля убраны из seo.jsonLd.

Что должен сделать frontend:

  • не рендерить на public seller page контакты и соцсети
  • не ожидать эти поля в response

6. Item contract для MVP

POST /api/v1/seller/items

PUT /api/v1/seller/items/:id

POST /api/v1/seller/items/:id/submit

Изменение бизнес-правила:

  • priceFrom должен быть строго больше 0
  • priceTo, если передаётся, тоже должен быть строго больше 0
  • item с бесплатной ценой для MVP больше невалиден

Дополнительно:

  • при отправке на модерацию backend теперь тоже требует валидный priceFrom > 0

Что должен сделать frontend:

  • убрать free-item сценарий
  • не давать вводить или отправлять 0
  • не маркировать item как бесплатный

7. Что фронту менять обязательно

  1. Во всех buyer child формах заменить age/birthYear на birthdate.
  2. В lead form передавать только itemId, childId, comment, source.
  3. Убрать guest lead flow и lead type toggle.
  4. В staff form сделать обязательными photoUrl и subjectId.
  5. Перевести teacher specialization на GET /api/v1/catalog/subjects.
  6. Убрать UI для Seller Manager.
  7. Убрать UI для block/unblock staff.
  8. На public seller page перестать ожидать контакты и соцсети.
  9. На item create/edit убрать free semantics и цену 0.

8. Что уже обновлено на backend

  • shared zod schemas
  • Prisma schema и migration
  • auth repository
  • buyer repository/service
  • lead controller/service/repository
  • staff controller/service/repository/module
  • seller public profile service
  • item moderation validation
  • OpenAPI schema export

9. Где смотреть контракт