Техническое описание первой итерации

Данный документ описывает техническую архитектуру первой итерации приложения с учетом новых требований:

• Введение системы модерации услуг перед их публикацией в ленте.
• Подробное описание взаимодействия заказчика и исполнителя, включая этапы обсуждения и подтверждения заказа.
• Платформа удерживает 100% средств после оплаты заказа заказчиком.

Технологический стек остается прежним: Next.js, ExpressJS, PostgreSQL.

Обзор системы

Компоненты системы

1. Миниапка на Next.js:
• Регистрация и аутентификация пользователей.
• Создание и управление услугами (для исполнителей).
• Поиск и просмотр услуг (для заказчиков).
• Управление заказами.
• Оставление отзывов и оценок.
• Интерфейс для модераторов для одобрения услуг.
2. Backend API сервер:
• Обработка бизнес-логики и взаимодействие с базой данных.
• Аутентификация и авторизация пользователей.
• Управление услугами, заказами и модерацией.
• Обработка платежей.
3. База данных (PostgreSQL):
• Хранение данных пользователей, услуг, заказов, сообщений, отзывов и модерации.
4. Telegram-бот:
• Обеспечение обмена сообщениями между заказчиком и исполнителем по конкретному заказу.
• Отправка уведомлений о новых сообщениях и изменениях статуса заказа.
5. Интеграция платежей:
• Криптовалютные платежи через TON (TON и USDT).
• Фиатные платежи через Stripe.

Пользовательские роли

1. Заказчик (Customer): пользователь, который ищет и заказывает услуги.
2. Исполнитель (Freelancer): пользователь, который предлагает услуги и выполняет заказы.
3. Модератор (Moderator): пользователь с дополнительными правами для проверки и одобрения услуг перед их публикацией.

Пользовательские сценарии взаимодействия

1. Регистрация и аутентификация

Регистрация пользователя

• Процесс:
• Пользователь заполняет форму регистрации в миниапке, указывая email и пин-код.
• Подтверждает регистрацию через email.
• Профиль пользователя создается в базе данных с ролью customer или freelancer (по умолчанию customer).
• Реализация:
• Фронтенд отправляет запрос POST /api/auth/register на бэкэнд.
• Бэкэнд создает запись в таблице users в базе данных.
• Используются JWT для аутентификации и управления сессиями.

Вход в систему

• Процесс:
• Пользователь вводит свои учетные данные для входа.
• Получает JWT-токен после успешной аутентификации.
• Реализация:
• Фронтенд отправляет запрос POST /api/auth/login на бэкэнд.
• Бэкэнд проверяет учетные данные и возвращает JWT-токен.

2. Создание и модерация услуг (для исполнителя)

Создание услуги

• Процесс:
• Исполнитель заполняет форму создания услуги:
• Название услуги.
• Подробное описание.
• Категория и теги.
• Предварительная цена (может быть скорректирована после обсуждения с заказчиком).
• Примерные сроки выполнения.
• Отправляет услугу на модерацию.
• Реализация:
• Фронтенд отправляет запрос POST /api/services на бэкэнд.
• Услуга сохраняется в базе данных со статусом pending.
• Услуга недоступна в поиске до одобрения модератором.

Модерация услуги

• Процесс:
• Модераторы просматривают список услуг со статусом pending.
• Проверяют услугу на соответствие правилам платформы.
• Одобряют или отклоняют услугу, возможно с комментарием.
• Реализация:
• Модераторы входят в миниапку с правами модератора.
• Доступен интерфейс модерации услуг.
• Бэкэнд предоставляет эндпоинты:
• GET /api/moderation/services — получить список услуг на модерации.
• POST /api/moderation/services/:id/approve — одобрить услугу.
• POST /api/moderation/services/:id/reject — отклонить услугу с указанием причины.
• После одобрения статус услуги меняется на active, и она становится доступна в поиске.

3. Поиск и выбор услуг (для заказчика)

Поиск услуг

• Процесс:
• Заказчик использует поисковую строку или фильтры для поиска услуг.
• Может просматривать категории, сортировать по различным критериям.
• Реализация:
• Фронтенд отправляет запросы GET /api/services с параметрами фильтрации и сортировки.
• Бэкэнд возвращает список услуг со статусом active.

Просмотр деталей услуги

• Процесс:
• Заказчик просматривает подробности услуги:
• Описание.
• Предварительная цена.
• Сроки выполнения.
• Портфолио исполнителя.
• Отзывы и оценки других заказчиков.
• Реализация:
• Фронтенд отображает данные услуги, полученные от бэкэнда (GET /api/services/:id).

4. Взаимодействие между заказчиком и исполнителем перед оплатой

Инициация общения

• Процесс:
• Заказчик заинтересован в услуге и нажимает кнопку "Связаться с исполнителем" или "Оформить заказ".
• Открывается чат или форма для отправки сообщения исполнителю с дополнительными пожеланиями или вопросами.
• Реализация:
• Фронтенд предоставляет интерфейс для отправки сообщения.
• Сообщение отправляется на бэкэнд (POST /api/communications/initiate).
• Бэкэнд создает запись в таблице communications и уведомляет исполнителя.

Общение и уточнение деталей

• Процесс:
• Исполнитель получает уведомление о заинтересованности заказчика.
• Через миниапку заказчик и исполнитель обмениваются сообщениями, обсуждая детали заказа:
• Дополнительные требования.
• Окончательная цена.
• Сроки выполнения.
• Четкий перечень того, что заказчик получит по завершении.
• Реализация:
• Фронтенд реализует чат между пользователями внутри миниапки.
• Сообщения отправляются на бэкэнд (POST /api/communications/messages) и сохраняются в базе данных.
• Уведомления об новых сообщениях могут отправляться через Telegram-бота для оперативности.

Установка окончательной цены и условий

• Процесс:
• После обсуждения исполнитель формирует окончательное предложение:
• Устанавливает окончательную цену.
• Определяет сроки выполнения.
• Описывает детали и результаты работы.
• Предложение отправляется заказчику для подтверждения.
• Реализация:
• Исполнитель отправляет предложение через миниапку (POST /api/orders/proposal).
• Бэкэнд создает запись в таблице orders со статусом awaiting_payment.
• Заказчик получает уведомление и может просмотреть предложение.

5. Оформление и оплата заказа

Принятие решения заказчиком

• Процесс:
• Заказчик просматривает предложение исполнителя.
• Может принять или отклонить предложение.
• В случае принятия переходит к оплате.
• Реализация:
• Фронтенд отображает детали предложения и кнопки "Оплатить" или "Отклонить".
• При оплате отправляется запрос POST /api/orders/:id/pay.

Оплата заказа

• Процесс:
• Заказчик выбирает способ оплаты (криптовалюта или фиат).
• Выполняет платеж.
• Платформа удерживает 100% суммы до завершения заказа.
• Реализация:
• Интеграция с платежными системами:
• Криптовалюта: Генерация адреса для оплаты и отслеживание поступления средств.
• Фиат: Перенаправление на платежную страницу Stripe и обработка webhooks.
• После успешного платежа статус заказа обновляется на paid.

6. Выполнение заказа и обмен сообщениями через Telegram-бота

Инициация чата в Telegram

• Процесс:
• После оплаты заказа бэкэнд уведомляет Telegram-бота о необходимости создания чата.
• Бот инициирует приватный чат между заказчиком и исполнителем.
• Реализация:
• Бэкэнд отправляет команду боту с идентификаторами пользователей и заказа.
• Бот использует node-telegram-bot-api для создания чата или группы.

Обмен сообщениями и выполнение работы

• Процесс:
• Заказчик и исполнитель общаются через Telegram-бота.
• Исполнитель выполняет работу в соответствии с согласованными условиями.
• По завершении исполнитель отправляет результаты работы заказчику.
• Реализация:
• Сообщения пересылаются через бота и могут сохраняться в базе данных для истории.
• Бот может предоставлять команды для обновления статуса заказа.

7. Завершение заказа и выплата средств исполнителю

Подтверждение завершения заказа

• Процесс:
• Исполнитель отмечает заказ как выполненный через миниапку или команду бота.
• Заказчик получает уведомление и проверяет результаты работы.
• Если заказчик удовлетворен, он подтверждает завершение заказа.
• Реализация:
• Исполнитель отправляет запрос PUT /api/orders/:id/complete.
• Заказчик подтверждает завершение через миниапку (PUT /api/orders/:id/confirm).
• Статус заказа обновляется на completed.

Выплата средств исполнителю

• Процесс:
• После подтверждения завершения заказа средства, удерживаемые платформой, перечисляются исполнителю.
• Реализация:
• Бэкэнд инициирует выплату:
• Криптовалюта: Отправка средств на кошелек исполнителя в TON.
• Фиат: Использование Stripe Payouts для перевода средств.
• Комиссии платформы удерживаются согласно политике.

8. Оставление отзывов и оценок

Оставление отзыва заказчиком

• Процесс:
• Заказчик оставляет отзыв и оценку исполнителю и услуге.
• Отзыв отображается на странице услуги и в профиле исполнителя.
• Реализация:
• Фронтенд предоставляет форму для отзыва.
• Запрос отправляется на бэкэнд (POST /api/reviews).
• Отзыв сохраняется в базе данных и отображается в интерфейсе.

Технические детали реализации

1. База данных

Модель User

sql
Copy code
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password VARCHAR(255) NOT NULL,
  role VARCHAR(20) CHECK (role IN ('customer', 'freelancer', 'moderator')) NOT NULL DEFAULT 'customer',
  name VARCHAR(100),
  rating INTEGER DEFAULT 0,
  wallet_address VARCHAR(100),
  stripe_account_id VARCHAR(100),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Модель Service

sql
Copy code
CREATE TABLE services (
  id SERIAL PRIMARY KEY,
  freelancer_id INTEGER REFERENCES users(id),
  title VARCHAR(255) NOT NULL,
  description TEXT NOT NULL,
  category VARCHAR(100),
  price DECIMAL(10, 2),
  status VARCHAR(20) CHECK (status IN ('pending', 'active', 'rejected')) DEFAULT 'pending',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Модель Order

sql
Copy code
CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  service_id INTEGER REFERENCES services(id),
  customer_id INTEGER REFERENCES users(id),
  freelancer_id INTEGER REFERENCES users(id),
  details TEXT NOT NULL,
  price DECIMAL(10, 2) NOT NULL,
  status VARCHAR(20) CHECK (status IN ('awaiting_payment', 'paid', 'in_progress', 'completed', 'cancelled')) DEFAULT 'awaiting_payment',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Модель Communication

sql
Copy code
CREATE TABLE communications (
  id SERIAL PRIMARY KEY,
  order_id INTEGER REFERENCES orders(id),
  customer_id INTEGER REFERENCES users(id),
  freelancer_id INTEGER REFERENCES users(id),
  created_at TIMESTAMP DEFAULT NOW()
);

Модель Message

sql
Copy code
CREATE TABLE messages (
  id SERIAL PRIMARY KEY,
  communication_id INTEGER REFERENCES communications(id),
  sender_id INTEGER REFERENCES users(id),
  content TEXT,
  sent_at TIMESTAMP DEFAULT NOW()
);

Модель Review

sql
Copy code
CREATE TABLE reviews (
  id SERIAL PRIMARY KEY,
  order_id INTEGER REFERENCES orders(id),
  reviewer_id INTEGER REFERENCES users(id),
  reviewed_user_id INTEGER REFERENCES users(id),
  rating INTEGER CHECK (rating BETWEEN 1 AND 5),
  comment TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

2. API эндпоинты

Аутентификация

• POST /api/auth/register — регистрация пользователя.
• POST /api/auth/login — вход в систему.

Услуги

• POST /api/services — создание услуги (только для исполнителей).
• GET /api/services — поиск и просмотр услуг.
• GET /api/services/:id — получение деталей услуги.
• PUT /api/services/:id — обновление услуги (исполнителем).
• DELETE /api/services/:id — удаление услуги (исполнителем).

Модерация

• GET /api/moderation/services — получить список услуг на модерации (только для модераторов).
• POST /api/moderation/services/:id/approve — одобрить услугу.
• POST /api/moderation/services/:id/reject — отклонить услугу.

Коммуникации

• POST /api/communications/initiate — инициация общения между заказчиком и исполнителем.
• POST /api/communications/messages — отправка сообщения в коммуникации.
• GET /api/communications/:id/messages — получение списка сообщений.

Заказы

• POST /api/orders/proposal — исполнитель отправляет предложение заказа.
• PUT /api/orders/:id/pay — заказчик оплачивает заказ.
• PUT /api/orders/:id/complete — исполнитель отмечает заказ как выполненный.
• PUT /api/orders/:id/confirm — заказчик подтверждает завершение заказа.

Отзывы

• POST /api/reviews — оставление отзыва.

3. Фронтенд (Next.js)

• Интерфейс пользователя:
• Формы регистрации и входа.
• Страницы создания и редактирования услуг.
• Поиск и просмотр услуг.
• Чат для общения между заказчиком и исполнителем.
• Интерфейс модератора для проверки и одобрения услуг.
• Управление состоянием:
• Использование Context API или Redux для управления состоянием приложения.
• Хранение информации о текущем пользователе, заказах и услугах.
• Аутентификация:
• Хранение JWT-токена в cookies с флагом HttpOnly.
• Middleware для защиты маршрутов и проверки прав доступа.

4. Бэкэнд (ExpressJS)

• Структура приложения:
• Разделение на модули по функциональности: аутентификация, услуги, заказы, модерация, коммуникации.
• Использование контроллеров, сервисов и моделей.
• Аутентификация и авторизация:
• Использование jsonwebtoken для создания и проверки JWT.
• Middleware для проверки роли пользователя (заказчик, исполнитель, модератор).
• Валидация данных:
• Использование express-validator для валидации входящих данных.
• Обработка ошибок:
• Центральный обработчик ошибок для формирования единообразных ответов при ошибках.

5. Telegram-бот

• Инициализация чатов:
• Получение команд от бэкэнда для создания чатов между пользователями.
• Хранение соответствия между идентификаторами пользователей в системе и Telegram.
• Обработка сообщений:
• Пересылка сообщений между заказчиком и исполнителем.
• Обработка файлов и медиаконтента.
• Безопасность:
• Проверка прав доступа пользователей к чатам.
• Ограничение на типы и размеры отправляемых файлов.

6. Интеграция платежей

• Криптовалютные платежи:
• Генерация уникального адреса кошелька для каждого заказа.
• Отслеживание поступления платежа через взаимодействие с блокчейном TON.
• Обработка подтверждений транзакций.
• Фиатные платежи:
• Интеграция с Stripe Checkout для приема платежей.
• Обработка webhooks от Stripe для подтверждения платежей.
• Настройка Stripe Payouts для выплат исполнителям.

7. Безопасность

• Хранение данных:
• Пароли хранятся в хэшированном виде (bcrypt).
• Чувствительные данные шифруются в базе данных.
• Аутентификация:
• Использование HTTPS для всех запросов.
• JWT-токены с достаточным сроком действия и механизмом обновления.
• Защита от атак:
• Валидация и фильтрация входящих данных.
• Ограничение частоты запросов (rate limiting).
• Использование CORS для контроля доступа.