2025-11-11 02:55:41 +03:00

8.7 KiB

Raw Blame History

План реализации механики заданий (Tasks)

Обзор

Механика заданий позволяет пользователям выполнять различные задачи для изучения языков. Задания могут быть как внутри приложения (тесты, игры), так и внешними (подписки, реальные разговоры). Задания формируются и хранятся на бэкенде.

Примеры заданий

Пройди 3 теста сегодня
Подпишись на канал в Telegram
Сделай заказ в ресторане на испанском и запиши это на видео

Архитектура

Модели данных

Task (Задание)

@freezed
class Task with _$Task {
  const factory Task({
    required String id,
    required String title,
    required String description,
    required TaskType type,
    required TaskDifficulty difficulty,
    required List<TaskReward> rewards,
    required TaskStatus status,
    required DateTime createdAt,
    required DateTime expiresAt,
    DateTime? completedAt,
    String? proofUrl, // ссылка на доказательство (видео, фото)
  }) = _Task;
}

TaskType (Тип задания)

enum TaskType {
  appInternal,    // внутри приложения (тесты, игры)
  external,       // внешние задания (реальные ситуации)
  social,         // социальные (подписки, репосты)
}

TaskDifficulty (Сложность)

enum TaskDifficulty {
  easy,
  medium,
  hard,
}

TaskStatus (Статус)

enum TaskStatus {
  available,      // доступно для выполнения
  inProgress,     // в процессе выполнения
  completed,      // выполнено
  expired,        // истекло
  failed,         // провалено
}

TaskReward (Награда)

@freezed
class TaskReward with _$TaskReward {
  const factory TaskReward({
    required RewardType type,
    required int amount,
  }) = _TaskReward;
}

enum RewardType {
  xp,              // опыт
  coins,           // монеты
  achievement,     // достижение
}

TaskProgress (Прогресс пользователя)

@freezed
class TaskProgress with _$TaskProgress {
  const factory TaskProgress({
    required String userId,
    required Map<String, TaskStatus> taskStatuses,
    required Map<String, DateTime> completedTasks,
    required int totalXp,
    required int totalCoins,
    required List<String> achievements,
  }) = _TaskProgress;
}

API Endpoints

Получение списка заданий

GET /api/tasks
Query params:
- user_id: String
- status: TaskStatus? (фильтр по статусу)
- type: TaskType? (фильтр по типу)
- limit: int? (ограничение количества)

Получение конкретного задания

GET /api/tasks/{taskId}

Обновление статуса задания

PUT /api/tasks/{taskId}/status
Body: {
  "status": TaskStatus,
  "proof_url": String?, // для внешних заданий
}

Получение прогресса пользователя

GET /api/users/{userId}/task-progress

Обновление прогресса

PUT /api/users/{userId}/task-progress
Body: {
  "task_id": String,
  "status": TaskStatus,
  "proof_url": String?,
}

State Management

TasksStateManager

class TasksStateManager extends YxStateManager<TasksState> {
  final TasksRepository _repository;
  final UserStateManager _userManager;

  // Методы:
  Future<void> loadTasks();
  Future<void> loadUserProgress();
  Future<void> updateTaskStatus(String taskId, TaskStatus status);
  Future<void> submitTaskProof(String taskId, String proofUrl);
  Future<List<Task>> getAvailableTasks();
  Future<List<Task>> getCompletedTasks();
  Future<TaskProgress> getUserProgress();
}

TasksState

@freezed
class TasksState with _$TasksState {
  const factory TasksState({
    required List<Task> tasks,
    required TaskProgress? userProgress,
    required bool isLoading,
    required String? error,
  }) = _TasksState;
}

UI Компоненты

Страница заданий (TasksPage)

Список доступных заданий
Фильтры по типу/статусу
Прогресс бар
Награды

Карточка задания (TaskCard)

Заголовок и описание
Тип и сложность
Статус
Кнопка действия (начать/завершить)
Награды

Модальное окно подтверждения (TaskConfirmationDialog)

Для внешних заданий
Загрузка доказательства (фото/видео)
Подтверждение выполнения

Виджет прогресса (TasksProgressWidget)

Общий прогресс
Количество выполненных заданий
XP и монеты

Интеграция с существующими скоупами

UserScope

Добавить TasksStateManager в UserScope:

class UserScope extends YxScope {
  late final TasksStateManager tasksManager;

  @override
  Future<void> init() async {
    tasksManager = TasksStateManager(
      repository: ref.read(tasksRepositoryProvider),
      userManager: ref.read(userStateManagerProvider),
    );
    await tasksManager.init();
  }
}

Этапы реализации

Этап 1: Модели данных и API

Создать модели Task, TaskProgress и перечисления
Реализовать TasksRepository с моковыми данными
Настроить API клиент для работы с бэкендом

Этап 2: State Management

Создать TasksStateManager
Интегрировать в UserScope
Реализовать бизнес-логику загрузки и обновления заданий

Этап 3: UI Компоненты

Создать TaskCard виджет
Реализовать TasksPage
Добавить фильтры и сортировку
Создать TaskConfirmationDialog

Этап 4: Интеграция

Добавить навигацию
Обновить главное меню (добавить вкладку Задания)
Интегрировать с системой наград

Этап 5: Тестирование

Unit тесты для state manager
Widget тесты для UI компонентов
Integration тесты

Этап 6: Бэкенд интеграция

Заменить моковые данные на реальные API вызовы
Обработать ошибки сети
Добавить кэширование

Требования к дизайну

Адаптивность

Поддержка мобильных устройств (хотя проект web-only)
Responsive дизайн для разных экранов

UX/UI

Ясные инструкции для каждого задания
Визуальная обратная связь при выполнении
Анимации для наград
Push-уведомления о новых заданиях

Доступность

Поддержка клавиатуры
Screen reader compatibility
Высокий контраст

Метрики и аналитика

Количество выполненных заданий
Время выполнения заданий
Популярность типов заданий
Конверсия в повторные использования

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

Валидация proof_url на клиенте
Проверка на бэкенде
Защита от спама (rate limiting)
Модерация контента для пользовательских доказательств

Будущие улучшения

Персонализация: Задания на основе прогресса пользователя
Социальные фичи: Совместные задания, лидерборды
Геймификация: Серии заданий, достижения
AI генерация: Автоматическое создание заданий
Мобильная интеграция: QR-коды для внешних заданий

8.7 KiB Raw Blame History Unescape Escape