# Qadam Platform — статус реализации

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

- Статус документа: living document
- Актуально на: 31 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении платформенной архитектуры, roadmap или статуса реализации
- Область применения: канонические платформенные spec-документы для текущего ядра Qadam
- Связанные документы:
  - [Текущее состояние](../../docs/project/current-state.md)
  - [Roadmap](../../docs/project/roadmap.md)
  - [Индекс документации](../../docs/README.md)

## Статус: in-progress

## 1. Foundation

- [x] Split-репозитории `qadam-core` и `qadam-web` с `pnpm` workspace внутри каждого репозитория
- [x] Общие пакеты `@repo/prisma`, `@repo/shared`, `@repo/eslint-config`, `@repo/typescript-config`
- [x] Prisma schema, migrations, seed
- [x] Prisma data layer оформлен как отдельный пакет с generated client и select helpers
- [x] Backend skeleton на NestJS
- [x] Frontend skeleton на Next.js App Router
- [x] Базовый production deploy на текущем сервере
- [x] Автоматизированный backup baseline и off-host retention на production-сервере
- [x] Базовый OpenAPI/Swagger-контур опубликован на production (`/api/docs`, `/api/openapi.json`)
- [x] Web получил первый generated OpenAPI contract layer для request types
- [x] В репозитории зафиксирован versioned OpenAPI artifact и root sync/check workflow
- [x] Для `auth + leads + catalog + reviews + public seller profile + buyer reviews cabinet` реализован generated response contract layer во frontend
- [x] Seller leads экран переведён на общий query/mutation слой без прямых `fetch`-вызовов
- [x] Публичный reviews flow и форма отправки отзыва переведены на общий query/mutation слой без прямых `fetch`-вызовов
- [x] Roadmap-портал закрыт от доступа через primary host и больше не полагается только на nginx/basic-auth bypass prevention
- [x] Refresh token consume стал атомарным и больше не допускает reuse race через отдельные `GET`/`DEL`
- [x] Trust proxy ограничен loopback proxy, поэтому throttling различает реальных клиентов за nginx
- [x] API production runtime больше не слушает внешний интерфейс и закрыт за loopback-only reverse proxy
- [x] Публичная доступность айтема унифицирована для catalog, public seller profile, lead write-path и review write-path
- [x] `SELLER_STAFF` перестал направляться во frontend в неподдержанный seller area
- [x] Созданы и запушены bootstrap-репозитории `qadam-core` и `qadam-web`
- [x] `qadam-web` собирается из собственного OpenAPI artifact и не требует backend checkout для codegen/build
- [x] Production runtime переведён на `qadam-core` и `qadam-web`
- [x] Roadmap-портал вынесен из `apps/web` в отдельный standalone runtime `apps/roadmap` и отдельный `systemd` unit `qadam-roadmap`
- [~] Документация приведена к актуальному состоянию, но ещё требует регулярного сопровождения
- [~] Docker-контур уже начат: для `api` есть актуальный Dockerfile, compose manifest и подтверждённый container smoke, но production всё ещё канонически host-based
- [~] Legacy checkout `/data/uzbek` всё ещё лежит на сервере, но больше не является production source of truth

## 2. Auth и аккаунты

- [x] Регистрация
- [x] Логин
- [x] `GET /auth/me`
- [x] Logout
- [x] Refresh token rotation через `httpOnly` cookies
- [~] Набор unit-тестов отставал от refresh-token реализации и должен поддерживаться актуальным
- [ ] SMS / phone verification

## 3. Buyer

- [x] Базовый buyer module на backend
- [x] `GET /me/profile`
- [x] `POST /me/profile`
- [x] `PATCH /me/profile`
- [x] Buyer leads API
- [x] Buyer reviews API
- [~] Buyer cabinet присутствует во frontend, но не доведён до полноценного UX
- [~] Buyer profile flow требует продуктовой и UI-доработки
- [ ] Полноценный buyer onboarding

## 4. Seller

- [x] Seller profile API
- [x] Seller items API
- [x] Seller leads API
- [x] Seller staff API
- [x] Seller cabinet routes во frontend
- [~] Seller onboarding и seller profile ещё не завершены с продуктовой точки зрения
- [~] Item workflow реализован частично и требует доводки статусов, UX и smoke-проверок
- [ ] Telegram notifications
- [ ] Финальная статусная модель seller-операций

## 5. Catalog и публичные страницы

- [x] Публичный каталог
- [x] Страница айтема `/item/[slug]`
- [x] Public seller profile `/sellers/[id]`
- [x] API для subjects и locations
- [~] SEO-слой частично присутствует, но не завершён
- [~] Фильтры и визуальная часть каталога ещё требуют доработки
- [ ] Карта и геопоиск
- [ ] Structured data, sitemap, canonical SEO-completion

## 6. Leads и reviews

- [x] Создание лидов
- [x] Лиды у buyer и seller
- [x] Базовый reviews flow
- [~] Расширенная статусная модель лидов пока не доведена до финальной
- [~] Модерация отзывов неполная
- [ ] CPL billing
- [ ] Нотификации по лидам

## 7. Admin

- [x] Admin routes и backend-модуль
- [x] Базовая статистика
- [x] Очередь модерации айтемов
- [x] CRUD по reference data на API-уровне
- [~] Реальная ролевая модель админов ещё не завершена
- [~] UI админки требует доводки
- [ ] Полный moderation workflow для отзывов
- [ ] Операционные роли root/verifier/analyst/marketing

## 8. Tracking и аналитика

- [x] Базовый tracking endpoint
- [x] Infrastructure layer для event logging
- [x] Структурное JSON-логирование через Pino и `nestjs-pino`
- [x] Optional Axiom transport в production при наличии credentials
- [x] Append-only таблица `EventLog` в Prisma schema
- [x] Внешний uptime/TLS monitoring и Telegram alert delivery baseline
- [~] Product analytics и seller-facing метрики реализованы частично
- [ ] Полноценная аналитическая витрина
- [ ] PMF, funnel и billing-аналитика

## 9. Документация и roadmap-портал

- [x] Отдельный домен `qadam-roadmap.2fab.app`
- [x] Basic auth
- [x] Чтение markdown напрямую из папки `docs/`
- [x] Переходы в `specs` и `docs/Agents` по относительным markdown-ссылкам
- [x] Архив processed plans скрывается по умолчанию и показывается только через `Show archived`
- [x] Upload/delete/comment для документов
- [x] TLS и отдельный host routing
- [x] Отдельный standalone runtime `qadam-roadmap` на `127.0.0.1:3001`
- [x] Отдельный operational docs/feedback портал для frontend-команды на `qadam-roadmap.2fab.app`

## 10. Quality Gates

- [x] Production build backend
- [x] Production build frontend
- [x] Repo-side quality gate на Gitea Actions с self-hosted runner
- [x] Исправлен production entrypoint API
- [x] Исправлено использование legacy frontend tree в production
- [x] Backend unit-тесты синхронизированы с текущей логикой auth и buyer profile
- [~] Runtime OpenAPI-контур работает, artifact export и CI drift check уже введены, core product-срезы уже живут на generated response types, но pipeline ещё нужно дотянуть до admin/legacy API-layer
- [ ] Frontend automated tests
- [~] Полноценный CI/CD quality gate уже введён для `qadam-core`, но ещё не доведён для `qadam-web`
- [ ] Web smoke/e2e контур

## 11. Ближайшие следующие шаги

1. Завершить buyer profile / buyer cabinet flow.
2. Масштабировать generated response contract layer с core product-срезов на admin API и остаточный legacy API-layer.
3. Убрать дублирующиеся frontend-слои и остаточный legacy-хвост в `qadam-web`.
4. Добавить базовые smoke/e2e-проверки на web.
5. Довести начатый docker/image-based delivery до web + registry + cutover и только после этого отказываться от host-based deploy как единственного runtime.

## 12. Сессионные заметки

### 2026-03-27

- Документация приведена к каноническому русскоязычному набору.
- Подтверждена рабочая production-модель: `systemd` + `nginx` + host services.
- Зафиксировано, что проект находится в состоянии `in-progress`, а не `not-started`.
- Поднят базовый OpenAPI/Swagger-контур и опубликован на production-домене.
- В `apps/web` подключён первый generated OpenAPI contract layer и убраны runtime DTO-зависимости от backend/shared пакетов.
- В репозитории зафиксирован versioned OpenAPI artifact, а CI теперь проверяет contract drift автоматически.
- Core product-срез `catalog + reviews + public seller profile + buyer reviews cabinet` переведён на generated response contract и общий API-layer.
- Отдельный security-hardening пакет закрыл roadmap host bypass, refresh race, throttling behind proxy и дрейф публичной доступности айтемов.
- API дополнительно закрыт на loopback bind, чтобы не обходить nginx напрямую по host port.
- Созданы и запушены bootstrap-репозитории `qadam-core` и `qadam-web`, оба подтверждены автономной установкой и сборкой.
- Production runtime и roadmap-портал переведены на `qadam-core` и `qadam-web`; `/data/uzbek` остался только как legacy checkout.