# 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
- Связанные документы:
  - [Индекс документации](../README.md)
  - [frontend-handoff.md](./frontend-handoff.md)
  - [openapi.json](../../apps/api/openapi/openapi.json)
  - [requirements.md](../project/requirements.md)

- Статус: 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`

Пример:

```json
{
  "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`

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

```json
{
  "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`

Пример:

```json
{
  "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`.

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

```json
{
  "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:

```json
{
  "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-контракта этого списка

Пример:

```json
{
  "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. Где смотреть контракт

- OpenAPI artifact: [apps/api/openapi/openapi.json](../../apps/api/openapi/openapi.json)
- Документ handoff: [frontend-mvp-cto-backend-handoff-2026-04-14.md](./frontend-mvp-cto-backend-handoff-2026-04-14.md)