412 lines
15 KiB
Markdown
412 lines
15 KiB
Markdown
# 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<ScheduleUiState> = _uiState.asStateFlow()
|
||
|
||
fun loadSchedules(userId: String) { /* ... */ }
|
||
}
|
||
|
||
data class ScheduleUiState(
|
||
val schedules: List<Schedule> = 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<List<Schedule>> {
|
||
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<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:
|
||
```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/)
|
||
|
||
---
|
||
|
||
*Последнее обновление: на основе текущей структуры проекта*
|
||
|