diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ee12a8f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,411 @@ +# 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 + +```kotlin +@HiltViewModel +class ScheduleViewModel @Inject constructor( + private val getSchedulesUseCase: GetSchedulesUseCase +) : ViewModel() { + private val _uiState = MutableStateFlow(ScheduleUiState()) + val uiState: StateFlow = _uiState.asStateFlow() + + fun loadSchedules(userId: String) { /* ... */ } +} + +data class ScheduleUiState( + val schedules: List = emptyList(), + val isLoading: Boolean = false +) +``` + +### Composable Screen + +```kotlin +@Composable +fun ScheduleScreen( + viewModel: ScheduleViewModel = hiltViewModel(), + modifier: Modifier = Modifier +) { + val uiState by viewModel.uiState.collectAsState() + + Scaffold(topBar = { /* ... */ }) { paddingValues -> + // UI content + } +} +``` + +### Repository + +```kotlin +class ScheduleRepositoryImpl @Inject constructor( + private val scheduleDao: ScheduleDao, + private val taskDao: TaskDao +) : ScheduleRepository { + override fun getSchedules(userId: String): Flow> { + return scheduleDao.getSchedulesByUserId(userId).map { /* ... */ } + } +} +``` + +--- + +## 🔌 API и сеть + +### Backend API + +- **Base URL**: `https://api.novayaplaneta.ru/` +- **Аутентификация**: Bearer Token в заголовке `Authorization` +- **Формат**: JSON (Kotlinx Serialization) + +### Эндпоинты (примеры) + +```kotlin +@POST("api/v1/auth/login") +suspend fun login(@Body request: LoginRequest): Response + +@POST("api/v1/ai/chat") +suspend fun chatWithAI( + @Header("Authorization") token: String, + @Body request: ChatRequest +): Response +``` + +### Обработка ошибок + +- Используется `Result` для обработки успешных/ошибочных результатов +- Локальные ошибки логируются, сетевые ошибки показываются пользователю + +--- + +## 💾 База данных (Room) + +### Стратегия + +- **Offline-first**: данные сначала сохраняются в Room +- **Синхронизация**: периодическая синхронизация с сервером +- **Flow**: все запросы возвращают `Flow` для реактивности + +### Entity → Domain Mapping + +Используются extension functions: +```kotlin +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) + +Команды: +```bash +./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](https://m3.material.io/) +- [Jetpack Compose](https://developer.android.com/jetpack/compose) +- [Hilt](https://dagger.dev/hilt/) +- [Room](https://developer.android.com/training/data-storage/room) +- [Retrofit](https://square.github.io/retrofit/) + +--- + +*Последнее обновление: на основе текущей структуры проекта* +