New-planet-app/CLAUDE.md

CLAUDE.md — Новая Планета (Android)

Справочная информация для AI-ассистента о проекте Новая Планета

---

🎯 О проекте

Новая Планета — Android-приложение для помощи детям с расстройством аутистического спектра (РАС) через:

• 📅 Визуальные расписания (день/неделя)
• ⏱️ Визуальный таймер (круговой с цветовой индикацией)
• 🎁 Систему наград за выполненные задания
• 🌍 ИИ-агента "Земля" для ответов и генерации расписаний
• 📚 Библиотеку изображений
• 👨‍👩‍👧 Роли: ребёнок, родитель, педагог

Важно: Приложение должно следовать принципам доступности (accessibility) для людей с РАС — высокая контрастность, крупные элементы, простые иконки.

---

🏗️ Архитектура

Clean Architecture + MVVM

Проект использует Clean Architecture с разделением на 3 слоя:

com.novayaplaneta/
├── domain/          # Бизнес-логика (не зависит от Android)
│   ├── model/       # Доменные модели
│   ├── repository/  # Интерфейсы репозиториев
│   └── usecase/     # Use cases (бизнес-правила)
│
├── data/            # Реализация источников данных
│   ├── local/       # Room (Entity, DAO, Database)
│   ├── remote/      # Retrofit (DTO, API)
│   └── repository/  # Реализации репозиториев
│
└── ui/              # Presentation Layer (Jetpack Compose)
    ├── screens/     # Экраны (Screen + ViewModel)
    ├── components/  # Переиспользуемые UI-компоненты
    ├── navigation/  # Навигация
    └── theme/       # Тема и стили

Принципы:

1. Dependency Rule: Внутренние слои не зависят от внешних

   • domain не знает о data и ui
   • data зависит от domain (реализует интерфейсы)
   • ui зависит от domain (использует модели и use cases)

2. MVVM: ViewModel связывает UI и бизнес-логику

   • ViewModel получает данные через Use Cases
   • UI наблюдает за StateFlow/LiveData в ViewModel
   • ViewModel не знает о Compose напрямую

3. Offline-first: Room — основной источник данных, Retrofit — для синхронизации

---

📦 Технологический стек

Язык и платформа

• Kotlin 2.0.21
• Android SDK: compileSdk 36, targetSdk 36, minSdk 26
• JDK 17

UI

• Jetpack Compose (BOM 2024.09.00)
• Material Design 3
• Navigation Component (Compose)

Архитектурные компоненты

• Hilt 2.53 — Dependency Injection
• KSP 2.0.21-1.0.25 — для кодогенерации (Room, Hilt)
• Lifecycle ViewModel Compose — интеграция ViewModel с Compose
• Coroutines + Flow — асинхронность

Data

• Room 2.6.1 — локальная БД (offline-first)
• Retrofit 2.11.0 — REST API
• OkHttp 4.12.0 — HTTP клиент
• Kotlinx Serialization — JSON сериализация

Другие библиотеки

• Coil 2.7.0 — загрузка изображений
• Lottie 6.1.0 — анимации

---

📂 Структура пакетов

Domain Layer (domain/)

domain/model/

Доменные модели (data classes), не зависят от Android/фреймворков:

• User.kt — пользователь с ролями (CHILD, PARENT, TEACHER)
• Schedule.kt — расписание с задачами
• Task.kt — задача/задание
• Reward.kt — награда
• ChatMessage.kt — сообщение от ИИ

domain/repository/

Интерфейсы репозиториев (без реализации):

• AuthRepository — аутентификация
• ScheduleRepository — работа с расписаниями
• TaskRepository — работа с задачами
• RewardRepository — работа с наградами
• AIRepository — взаимодействие с ИИ

domain/usecase/

Use Cases — инкапсулируют бизнес-логику:

• GetSchedulesUseCase — получение расписаний
• CreateScheduleUseCase — создание расписания
• CompleteTaskUseCase — завершение задачи
• SendAIMessageUseCase — отправка сообщения ИИ

Правило: Use Case принимает интерфейсы репозиториев через конструктор (DI).

---

Data Layer (data/)

data/local/

Room Database:

• entity/ — Room entities (таблицы БД)
  • Используют Long для timestamps (вместо LocalDateTime)
  • Префикс Entity (например, UserEntity)
• dao/ — Data Access Objects (запросы к БД)
  • Используют Flow для реактивных данных
  • Префикс Dao (например, UserDao)
• mapper/ — мапперы между Entity ↔ Domain
  • Extension functions: toDomain(), toEntity()
  • Пример: UserMapper.kt, ScheduleMapper.kt
• NewPlanetDatabase.kt — главный класс Room Database

data/remote/

Retrofit API:

• BackendApi.kt — интерфейс Retrofit с эндпоинтами
  • Base URL: https://api.novayaplaneta.ru/
  • Использует Kotlinx Serialization
• dto/ — Data Transfer Objects (DTO) для API
  • Префикс Request/Response (например, LoginRequest, LoginResponse)
  • Используют @Serializable из kotlinx.serialization

data/repository/

Реализации репозиториев:

• AuthRepositoryImpl — реализует AuthRepository
• ScheduleRepositoryImpl — реализует ScheduleRepository
• TaskRepositoryImpl — реализует TaskRepository
• RewardRepositoryImpl — реализует RewardRepository
• AIRepositoryImpl — реализует AIRepository

Правило:

• Репозиторий объединяет данные из Room (local) и Retrofit (remote)
• Использует мапперы для конвертации Entity → Domain
• Отдает Flow из Room для реактивности

---

UI Layer (ui/)

ui/screens/

Экраны организованы по функциональности:

• schedule/ — ScheduleScreen.kt + ScheduleViewModel.kt
• task/ — TaskScreen.kt + TaskViewModel.kt
• timer/ — TimerScreen.kt + TimerViewModel.kt
• rewards/ — RewardsScreen.kt + RewardsViewModel.kt
• ai/ — AIScreen.kt + AIViewModel.kt
• settings/ — SettingsScreen.kt + SettingsViewModel.kt

Правило:

• Каждый экран — это @Composable функция с Scaffold
• ViewModel инжектируется через hiltViewModel()
• UI State хранится в StateFlow в ViewModel
• Экран наблюдает за UI State через collectAsState()

ui/components/

Переиспользуемые UI-компоненты:

• BottomNavigation.kt — нижняя навигационная панель с 6 пунктами

ui/navigation/

• NewPlanetNavigation.kt — NavHost с маршрутами

ui/theme/

• Color.kt — цвета темы (высокая контрастность для РАС)
• Theme.kt — Material3 тема (Light/Dark)
• Type.kt — типографика

---

DI (di/)

Hilt модули:

• DatabaseModule.kt — предоставляет Room Database и DAOs
• NetworkModule.kt — предоставляет Retrofit и OkHttp
• RepositoryModule.kt — привязывает интерфейсы к реализациям (@Binds)

Правило:

• Все модули используют @InstallIn(SingletonComponent::class)
• Используется KSP для кодогенерации (не KAPT)

---

🎨 Дизайн и доступность

Принципы доступности (РАС)

1. Крупные элементы — минимум 48dp для кликабельных областей
2. Высокая контрастность — WCAG AAA стандарт
3. Простые иконки — понятные, без лишних деталей
4. Цветовое кодирование — состояния имеют разные цвета
5. Плавные анимации — без мигания и резких переходов

Цветовая схема

Светлая тема:

• Фон: #FFFFFF, #F5F5F5
• Текст: #0A0A0A
• Акценты: #4CAF50 (зеленый), #FF6B35 (оранжевый)

Тёмная тема:

• Фон: #0A0A0A
• Текст: #FFFFFF
• Акценты: #4CAF50 (зеленый), #FFD700 (золотой)

Типографика

Используется Material3 Typography с настройками для читаемости (крупные размеры, хороший межстрочный интервал).

---

💻 Соглашения о коде

Именование

• Классы/Interfaces: PascalCase (ScheduleRepository, UserEntity)
• Функции/Переменные: camelCase (getSchedules, uiState)
• Константы: UPPER_SNAKE_CASE (если нужны)
• Пакеты: lowercase (без подчеркиваний)

Файлы

• Один класс/интерфейс = один файл
• Имя файла = имя класса
• Для Extension functions: имя файла описывает назначение (например, UserMapper.kt)

ViewModel

@HiltViewModel
class ScheduleViewModel @Inject constructor(
    private val getSchedulesUseCase: GetSchedulesUseCase
) : ViewModel() {
    private val _uiState = MutableStateFlow(ScheduleUiState())
    val uiState: StateFlow<ScheduleUiState> = _uiState.asStateFlow()
    
    fun loadSchedules(userId: String) { /* ... */ }
}

data class ScheduleUiState(
    val schedules: List<Schedule> = emptyList(),
    val isLoading: Boolean = false
)

Composable Screen

@Composable
fun ScheduleScreen(
    viewModel: ScheduleViewModel = hiltViewModel(),
    modifier: Modifier = Modifier
) {
    val uiState by viewModel.uiState.collectAsState()
    
    Scaffold(topBar = { /* ... */ }) { paddingValues ->
        // UI content
    }
}

Repository

class ScheduleRepositoryImpl @Inject constructor(
    private val scheduleDao: ScheduleDao,
    private val taskDao: TaskDao
) : ScheduleRepository {
    override fun getSchedules(userId: String): Flow<List<Schedule>> {
        return scheduleDao.getSchedulesByUserId(userId).map { /* ... */ }
    }
}

---

🔌 API и сеть

Backend API

• Base URL: https://api.novayaplaneta.ru/
• Аутентификация: Bearer Token в заголовке Authorization
• Формат: JSON (Kotlinx Serialization)

Эндпоинты (примеры)

@POST("api/v1/auth/login")
suspend fun login(@Body request: LoginRequest): Response<LoginResponse>

@POST("api/v1/ai/chat")
suspend fun chatWithAI(
    @Header("Authorization") token: String,
    @Body request: ChatRequest
): Response<ChatResponse>

Обработка ошибок

• Используется Result<T> для обработки успешных/ошибочных результатов
• Локальные ошибки логируются, сетевые ошибки показываются пользователю

---

💾 База данных (Room)

Стратегия

• Offline-first: данные сначала сохраняются в Room
• Синхронизация: периодическая синхронизация с сервером
• Flow: все запросы возвращают Flow для реактивности

Entity → Domain Mapping

Используются extension functions:

fun UserEntity.toDomain(): User { /* ... */ }
fun User.toEntity(): UserEntity { /* ... */ }

Миграции

При изменении схемы БД необходимо добавить миграцию в NewPlanetDatabase.

---

🧩 Dependency Injection (Hilt)

Структура

• @HiltAndroidApp на NewPlanetApplication
• @AndroidEntryPoint на MainActivity
• @HiltViewModel на ViewModels
• @Inject constructor() для зависимостей

Модули

• DatabaseModule — Room (Singleton)
• NetworkModule — Retrofit + OkHttp (Singleton)
• RepositoryModule — привязки интерфейсов (Singleton)

Важно: Используется KSP (не KAPT) для Room и Hilt.

---

🧪 Тестирование

• Unit тесты: test/ (JUnit)
• Instrumented тесты: androidTest/ (Espresso, Compose Testing)

Команды:

./gradlew test              # Unit тесты
./gradlew connectedAndroidTest  # Instrumented тесты

---

📝 Важные заметки

1. Offline-first: Приложение работает без интернета, данные берутся из Room
2. Accessibility: Все UI компоненты должны следовать принципам доступности для РАС
3. Роли пользователей: CHILD, PARENT, TEACHER — разные права доступа (будущая реализация)
4. ИИ-агент "Земля": чат-бот для помощи пользователям
5. Визуальный таймер: круговой индикатор с цветовым кодированием (важно для детей с РАС)

---

🚀 Быстрый старт

1. Установить JDK 17+
2. Открыть проект в Android Studio Hedgehog+
3. Синхронизировать Gradle
4. Запустить на эмуляторе/устройстве (minSdk 26)

---

📚 Полезные ссылки

• Material Design 3
• Jetpack Compose
• Hilt
• Room
• Retrofit

---

Последнее обновление: на основе текущей структуры проекта