GoodRoad-Project · KseniaG8 · Mar 17, 2026 · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026
diff --git a/LICENSE b/LICENSE
@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.
diff --git a/README.md b/README.md
@@ -1,47 +1,46 @@
-![Превью](images/readme_preview.png)
+<p align="center">
+  <img src="images/preview.png" alt="GoodRoad banner" width="974">
+</p>
 
 ## GoodRoad (Android client)
 
 **Авторы**: ```Городкова Ксения```, ```Грудцына Виктория```, ```Толстограева Виктория```
 
-## Описание проекта
-
-**GoodRoad** — это мобильное приложение для построения пеших инклюзивных маршрутов. В отличие от стандартной навигации по кратчайшему пути, приложение подстраивает путь под ограничения здоровья пользователя. Если полностью безбарьерного маршрута нет, GoodRoad показывает проблемные участки и дает возможность запросить помощь волонтера.
-
-Данные о доступности инфраструктуры собираются пользователями в игровом формате с системой бонусов. Запросы на помощь находятся в отдельной ленте.
-
-## Основная функциональность
-
-- **Профиль пользователя:**
-    - Выбор препятствий, которые нужно избегать при построении маршрута;
-    - Интерактивные задания, связанные с оценкой объектов и волонтерством;
-    - Рейтинг и система начисления баллов за отзывы и волонтерство;
-    - Лента заявок на помощь с фильтрами по местоположению и времени;
-    - Подача заявки на улучшение инфраструктуры.
-- **Профиль модератора:**
-    - Обработка заявок о помощи: система реагирования на критические ситуации;
-    - Модерация отзывов;
-- **Карта и маршруты:**
-    - Влияние отзывов на построение пути.
-    - Построение 3 вариантов маршрута: **доступный**, **быстрый**, **компромиссный**;
-    - Выделение проблемных участков и карточки объектов с деталями;
-    - История маршрутов и сохранение последнего построенного пути.
-
-## MVP
-
-- **Регистрация / вход / восстановление доступа.**
-- **Маршрутизация:**
-    - Выбор избегаемых препятствий в профиле;
-    - Построение маршрута;
-    - Отображение маршрута и проблемных участков;
-    - Хранение препятствий (тип и тяжесть).
-- **Отзывы:**
-    - Чек-лист для оценивания;
-    - Прикрепление фотографии (опционально);
-    - Учет отзывов в маршрутизации.
-- **Модерация:**
-    - Проверка отзывов;
-    - Управление младшими модераторами (в случае главного).
+## Краткое описание проекта
+
+**GoodRoad** — мобильное приложение для построения пеших инклюзивных маршрутов с учетом состояния дороги, препятствий на пути и персональных ограничений пользователя.
+
+Обычный навигатор часто показывает только самый короткий или быстрый путь, но не объясняет, насколько этот путь удобен на практике. На маршруте могут встретиться лестницы, высокие бордюры, ямы, крутые участки дороги и другие барьеры. GoodRoad решает именно эту задачу: приложение помогает заранее понять, подходит ли путь конкретному человеку, показывает проблемные места и позволяет собирать отзывы о доступности дорог и объектов.
+
+Сейчас проект представлен в формате MVP. В этой версии мы показываем основной сценарий работы приложения: пользователь настраивает ограничения, строит маршрут с учетом препятствий и оставляет отзывы, а модератор проверяет пользовательский контент.
+
+## Возможности для каждого типа пользователя (MVP)
+
+### Пользователь
+- Регистрация, вход, восстановление пароля;
+- Просмотр и редактирование профиля;
+- Выбор препятствий, которые нужно избегать при построении маршрута, и их тяжесть;
+- Построение маршрута с учетом ограничений пользователя;
+- Создание, редактирование и удаление отзывов о состоянии дороги или объекта;
+- Добавление фотографий к отзыву;
+- Просмотр статуса модерации отзыва и начисленных за него баллов.
+
+### Модератор
+- Просмотр отзывов, отправленных на проверку;
+- Одобрение и отклонение отзывов;
+- Работа с модерацией пользовательского контента.
+
+### Главный модератор
+- Все возможности обычного модератора;
+- Добавление и удаление других модераторов.
+
+## Что планируем добавить к защите
+
+- Дополнительные сценарии для построения маршрута;
+- Расширение работы с картой и подсветкой проблемных участков;
+- Взаимодействие с волонтерами: их поиск, связь и оказание помощи людям с ограниченными возможностями;
+- Расширение системы баллов в игровом формате: выполнение заданий, связанных с волонтерством и сбором данных о доступности дорог и объектов;
+- Расширение модераторского сценария.
 
 ## Наши продукты
 
@@ -54,57 +53,93 @@
   </tr>
   <tr>
     <td align="center">
-      <em>Временно недоступно</em>
+      <em>Скоро тут появится ссылка</em>
     </td>
   </tr>
 </table>
 
+## Как запустить backend в Docker
+На данный момент доступна локальная проверка клиентского приложения. Для этого рядом должен находиться серверный репозиторий [GoodRoad-Server](https://github.com/GoodRoad-Project/GoodRoadServer).
+Ожидаемая структура каталогов:
+```text
+GoodRoad-Client/
+GoodRoad-Server/
+```
 
-## Технологии
+### 1. Подготовьте `.env`
+Из корня клиентского репозитория выполните:
 
-<table>
-  <tr>
-    <th colspan="2" align="center">Основные технологии и инструменты (клиент)</th>
-  </tr>
-  <tr>
-    <th>Компонент</th>
-    <th>Технологии / Инструменты</th>
-  </tr>
-  <tr>
-    <td><strong>UI</strong></td>
-    <td>Android SDK, Material Components/ Jetpack Compose</td>
-  </tr>
-  <tr>
-    <td><strong>Карты</strong></td>
-    <td>Mapbox Android SDK (слои для маршрутов и препятствий)</td>
-  </tr>
-  <tr>
-    <td><strong>Геопозиция</strong></td>
-    <td>Android Location API</td>
-  </tr>
-  <tr>
-    <td><strong>Оффлайн-данные</strong></td>
-    <td>Room (кэш профиля, ограничений, препятствий и последнего маршрута)</td>
-  </tr>
-  <tr>
-    <td><strong>Геометрия</strong></td>
-    <td>JTS (офлайн-операции с геометрией при учете препятствий)</td>
-  </tr>
-</table>
+```bash
+cp docker/.env.backend.example docker/.env.backend
+```
 
-*Технологии серверной части: [в отдельном репозитории](https://github.com/GoodRoad-Project/GoodRoadServer).*
+При необходимости можно изменить значения в `docker/.env.backend`.
 
-## Архитектура клиента
+### 2. Запустите контейнеры
+Из корня `GoodRoad-Client`:
+
+```bash
+docker-compose up --build
+```
 
-**Временно недоступно**
+После запуска поднимутся PostgreSQL + PostGIS, а также backend GoodRoad на Spring Boot.
 
-## Безопасность
+### 3. Используйте сервер из Android-клиента
+В клиенте используется адрес:
 
-**Временно недоступно**
+```text
+http://10.0.2.2:8080/
+```
 
-## Структура проекта
+Этот адрес подходит для Android-эмулятора. Если запускаете приложение на физическом устройстве, адрес сервера нужно заменить на локальный IP компьютера в вашей сети.
 
-| **Схема клиентского приложения**<br>![Архитектура приложения](images/android_scheme.png) |
-|:----------------------------------------------------------------------------------------:|
+## Технологии клиента
+
+| Категория | Технологии | Назначение |
+|---|---|---|
+| Язык | Kotlin | Основной язык клиентского приложения |
+| UI | Jetpack Compose, Material 3 | Построение экранов и компонентов интерфейса |
+| Навигация | Navigation Compose | Переходы между экранами и сценариями |
+| Состояние экрана | ViewModel, LiveData | Хранение состояния и обработка логики экранов |
+| Асинхронность | Kotlin Coroutines | Выполнение сетевых и фоновых операций |
+| Сеть | Retrofit, OkHttp | Работа с REST API |
+| JSON | Gson Converter | Сериализация и десериализация DTO |
+| Изображения | Coil | Загрузка и отображение изображений |
+
+## Архитектура клиента
 
-*Схемы серверной части: [в отдельном репозитории](https://github.com/GoodRoad-Project/GoodRoadServer)*.
+Клиент реализован как Android-приложение на Jetpack Compose. Основной поток взаимодействия внутри клиента: **надо добавить**
+
+### Слои клиентской архитектуры
+
+| Слой | Что включает | Назначение |
+|----|---|---|
+| UI | `ui/auth`, `ui/user`, `ui/maps`, `ui/reviews`, `ui/theme` | Экраны, компоненты интерфейса, навигационные сценарии |
+| ViewModel | `AuthViewModel`, `UserViewModel`, `MapsViewModel`, `ReviewsViewModel` | Состояние экранов, обработка действий пользователя, связь UI и данных |
+| Data | `data/auth`, `data/user`, `data/obstacle`, `data/review`, `data/network` | Работа с DTO, репозиториями и сетевыми запросами |
+| Network | `ApiClient`, Retrofit API interfaces | Подключение к backend, настройка base URL, сериализация и HTTP-клиент |
+
+### Структура проекта
+
+```text
+app/src/main/java/com/example/goodroad/
+├── MainActivity.kt
+├── data/
+│   ├── auth/
+│   ├── network/
+│   ├── obstacle/
+│   ├── review/
+│   └── user/
+└── ui/
+    ├── auth/
+    ├── common/
+    ├── maps/
+    ├── reviews/
+    ├── theme/
+    ├── user/
+    └── viewmodel/
+```
+
+## Схема клиентского приложения
+
+**надо добавить (а может и не надо)**
diff --git a/SETUP.md b/SETUP.md
@@ -0,0 +1 @@
+## Тут что-то будет позже
diff --git a/app/build.gradle b/app/build.gradle
@@ -0,0 +1,120 @@
+plugins {
+    id 'com.android.application'
+    id 'org.jetbrains.kotlin.android'
+}
+
+android {
+    namespace 'com.example.goodroad'
+    compileSdk 35
+
+    defaultConfig {
+        applicationId 'com.example.goodroad'
+        minSdk 28
+        targetSdk 35
+        versionCode 1
+        versionName '1.0'
+
+        testInstrumentationRunner 'androidx.test.runner.AndroidJUnitRunner'
+        buildConfigField "boolean", "MOCK_AUTH", "false"
+        buildConfigField "String", "GOODROAD_SERVER_URL", "\"http://10.0.2.2:8080/\""
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+        debug {
+            applicationIdSuffix '.debug'
+            debuggable true
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+
+    buildFeatures {
+        compose true
+        buildConfig true
+    }
+
+    composeOptions {
+        kotlinCompilerExtensionVersion '1.5.14'
+    }
+
+    packaging {
+        resources {
+            excludes += '/META-INF/{AL2.0,LGPL2.1}'
+        }
+    }
+}
+
+dependencies {
+    implementation 'androidx.compose.foundation:foundation:1.10.5'
+    implementation 'androidx.compose.runtime:runtime-livedata:1.10.6'
+    implementation 'androidx.compose.runtime:runtime:1.10.6'
+    def composeBom = platform('androidx.compose:compose-bom:2024.06.00')
+
+    implementation 'androidx.core:core-ktx:1.15.0'
+    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.8.7'
+    implementation 'androidx.activity:activity-compose:1.9.3'
+    implementation composeBom
+    androidTestImplementation composeBom
+
+    implementation 'androidx.compose.ui:ui'
+    implementation 'androidx.compose.ui:ui-tooling-preview'
+    implementation 'androidx.compose.material3:material3'
+    implementation 'androidx.compose.material:material-icons-extended'
+    implementation 'androidx.navigation:navigation-compose:2.8.5'
+    implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:2.8.7'
+    implementation 'com.google.android.material:material:1.12.0'
+
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0'
+    implementation 'com.squareup.retrofit2:retrofit:2.11.0'
+    implementation 'com.squareup.retrofit2:converter-gson:2.11.0'
+    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
+    implementation 'io.coil-kt:coil-compose:2.7.0'
+
+    implementation 'org.maplibre.gl:android-sdk:13.0.2'
+    implementation 'com.google.maps.android:android-maps-utils:3.8.2'
+    implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.9.23'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3'
+    implementation 'androidx.core:core-ktx:1.12.0'
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+    implementation 'com.google.android.material:material:1.11.0'
+    implementation 'androidx.activity:activity:1.8.0'
+    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
+    testImplementation 'junit:junit:4.13.2'
+    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
+    implementation 'org.locationtech.jts:jts-core:1.20.0'
+    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
+    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
+    implementation 'org.maplibre.gl:android-sdk:13.0.2'
+    implementation 'com.google.android.gms:play-services-location:21.3.0'
+    implementation 'com.graphhopper:graphhopper-core:11.0'
+    implementation 'com.google.maps.android:android-maps-utils:3.4.0'
+    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
+    implementation 'com.google.maps.android:android-maps-utils:3.8.2'
+
+    debugImplementation 'androidx.compose.ui:ui-tooling'
+    debugImplementation 'androidx.compose.ui:ui-test-manifest'
+
+    implementation 'org.maplibre.gl:android-sdk:11.5.1'
+}
+
+configurations.all {
+    resolutionStrategy {
+        force 'org.jetbrains.kotlin:kotlin-stdlib:1.9.23'
+        force 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.9.23'
+        force 'org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.9.23'
+        force 'org.jetbrains.kotlin:kotlin-stdlib-common:1.9.23'
+    }
+}
diff --git a/app/proguard-rules.pro b/app/proguard-rules.pro
@@ -0,0 +1 @@
+# пока пусто
diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application
+        android:allowBackup="true"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="@xml/backup_rules"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.GoodRoad"
+        android:usesCleartextTraffic="true">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <activity
+            android:name=".MapActivity"
+            android:exported="false" />
+
+    </application>
+
+</manifest>