Initial commit3
This commit is contained in:
411
CLAUDE.md
Normal file
411
CLAUDE.md
Normal file
@@ -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<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/)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Последнее обновление: на основе текущей структуры проекта*
|
||||||
|
|
||||||
Reference in New Issue
Block a user