1505 lines
57 KiB
Markdown
1505 lines
57 KiB
Markdown
# 🏗️ Архитектура: Связь между Таблицами, Моделями, DTO и DAO
|
||
|
||
Документ объясняет, как связаны компоненты данных в проекте Mnemo Cards Backend.
|
||
|
||
---
|
||
|
||
## 📊 Общая схема связей
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ PostgreSQL Database │
|
||
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ users table │ │ user_datas │ │ card_packs │ │
|
||
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
↕ (SQL queries)
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Drift ORM (Code Generation) │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ 1. TABLES (lib/database/tables/*.dart) │ │
|
||
│ │ - Определение структуры таблиц │ │
|
||
│ │ class Users extends Table { ... } │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ ↕ (build_runner) │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ 2. MODELS (database.g.dart) │ │
|
||
│ │ - Автогенерация классов данных │ │
|
||
│ │ class User extends DataClass { ... } │ │
|
||
│ │ class UsersCompanion { ... } (для insert/update) │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ ↕ (DAO methods) │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ 3. DAO (lib/database/daos/*_dao.dart) │ │
|
||
│ │ - Методы для работы с БД │ │
|
||
│ │ class UserDao { Future<User?> getUserById(...) } │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
↕ (Extensions)
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Domain Models (mnemo_cards_common_backend) │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ 4. Domain Models (UserModel, UserDataModel) │ │
|
||
│ │ - Бизнес-логика приложения │ │
|
||
│ │ - Расширения для конвертации │ │
|
||
│ │ extension UserToUserModel on User { ... } │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
↕ (toDto())
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ DTO (mnemo_cards_common) │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ 5. DTO (UserDto, CardPackDto, etc.) │ │
|
||
│ │ - JSON сериализуемые объекты для API │ │
|
||
│ │ - Только данные, без логики │ │
|
||
│ │ extension UserModelExtension { UserDto toDto() } │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
↕ (toJson())
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ API Layer (Shelf) │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ 6. API Endpoints │ │
|
||
│ │ Response.ok(userDto.toJson()) │ │
|
||
│ │ - HTTP JSON responses │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 Детальный поток данных
|
||
|
||
### Пример: Получение пользователя через API
|
||
|
||
```dart
|
||
// 1. HTTP Request
|
||
GET /api/v2/users/me
|
||
|
||
// 2. API Endpoint (users_api_v2.dart)
|
||
@Route.get('/users/me')
|
||
Future<Response> getCurrentUser(Request request) async {
|
||
final user = request.user; // UserModel (domain model)
|
||
|
||
// 3. Конвертация в DTO
|
||
final dto = await user.toDto(); // UserModel → UserDto
|
||
|
||
// 4. JSON Response
|
||
return _json(dto.toJson()); // UserDto → JSON
|
||
}
|
||
```
|
||
|
||
### Пример: Получение данных из БД
|
||
|
||
```dart
|
||
// 1. Manager (user_manager.dart)
|
||
Future<UserModel?> fetchUser(String id) async {
|
||
// 2. DAO обращается к БД через Drift
|
||
final user = await _db.userDao.getUserById(id); // Returns: User (Drift model)
|
||
|
||
// 3. Конвертация Drift User → Domain UserModel
|
||
return await user?.toUserModel(); // User → UserModel
|
||
}
|
||
```
|
||
|
||
### Пример: Создание нового пользователя
|
||
|
||
```dart
|
||
// 1. API получает данные
|
||
POST /api/v2/auth/register
|
||
{ "email": "user@example.com", "password": "..." }
|
||
|
||
// 2. API вызывает Manager
|
||
await _userManager.createUser(email, password);
|
||
|
||
// 3. Manager использует DAO
|
||
final companion = UsersCompanion.insert(
|
||
email: email,
|
||
externalUserId: generateId(),
|
||
// ...
|
||
);
|
||
final userId = await _db.userDao.createUser(companion); // Insert в БД
|
||
|
||
// 4. Возврат созданной модели
|
||
final user = await _db.userDao.getUserById(userId);
|
||
return await user.toUserModel();
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Компоненты детально
|
||
|
||
### 1️⃣ **TABLES** (Определение структуры БД)
|
||
|
||
**Расположение:** `lib/database/tables/*.dart`
|
||
|
||
**Назначение:** Определяют структуру таблиц PostgreSQL через Drift
|
||
|
||
**Пример:**
|
||
|
||
```dart
|
||
// lib/database/tables/users.dart
|
||
class Users extends Table {
|
||
TextColumn get id => text()
|
||
.withDefault(const CustomExpression('gen_random_uuid()::text'))();
|
||
TextColumn get name => text().nullable()();
|
||
TextColumn get email => text().nullable()();
|
||
BoolColumn get admin => boolean()
|
||
.withDefault(const Constant(false))();
|
||
|
||
DateTimeColumn get createdAt => dateTime()
|
||
.withDefault(currentDateAndTime)();
|
||
|
||
@override
|
||
Set<Column> get primaryKey => {id};
|
||
}
|
||
```
|
||
|
||
**Что это дает:**
|
||
- ✅ Type-safe определение схемы БД
|
||
- ✅ Автоматическая генерация миграций
|
||
- ✅ Валидация на уровне компиляции
|
||
|
||
---
|
||
|
||
### 2️⃣ **MODELS** (Drift генерирует классы данных)
|
||
|
||
**Расположение:** `lib/database/database.g.dart` (автогенерируемый файл)
|
||
|
||
**Назначение:** Immutable классы данных для работы с записями из БД
|
||
|
||
**Пример:**
|
||
|
||
```dart
|
||
// Автогенерируется Drift из таблицы Users
|
||
class User extends DataClass implements Insertable<User> {
|
||
final String id;
|
||
final String externalUserId;
|
||
final String? name;
|
||
final String? email;
|
||
final bool admin;
|
||
final List<String> purchases;
|
||
final PgDateTime createdAt;
|
||
final PgDateTime updatedAt;
|
||
final bool isDeleted;
|
||
|
||
const User({
|
||
required this.id,
|
||
required this.externalUserId,
|
||
this.name,
|
||
this.email,
|
||
required this.admin,
|
||
// ...
|
||
});
|
||
|
||
// Автоматически генерируются:
|
||
// - toJson()
|
||
// - fromJson()
|
||
// - toCompanion()
|
||
// - copyWith()
|
||
}
|
||
```
|
||
|
||
**Companion классы** (для insert/update):
|
||
|
||
```dart
|
||
// Для создания/обновления записей
|
||
class UsersCompanion {
|
||
final Value<String> id;
|
||
final Value<String> externalUserId;
|
||
final Value<String?> name;
|
||
// ...
|
||
|
||
UsersCompanion.insert({
|
||
this.id = const Value.absent(), // auto-generated
|
||
required String externalUserId,
|
||
String? name,
|
||
// ...
|
||
}) : externalUserId = Value(externalUserId),
|
||
name = Value(name);
|
||
}
|
||
```
|
||
|
||
**Ключевые особенности:**
|
||
- ✅ Immutable (неизменяемые после создания)
|
||
- ✅ Type-safe (все типы проверяются компилятором)
|
||
- ✅ Автоматическая сериализация JSON
|
||
|
||
---
|
||
|
||
### 3️⃣ **DAO** (Data Access Objects)
|
||
|
||
**Расположение:** `lib/database/daos/*_dao.dart`
|
||
|
||
**Назначение:** Методы для CRUD операций с БД через Drift
|
||
|
||
**Пример:**
|
||
|
||
```dart
|
||
// lib/database/daos/user_dao.dart
|
||
@DriftAccessor(tables: [Users, UserDatas, Tokens, RefreshTokens, UserPacks])
|
||
class UserDao extends DatabaseAccessor<AppDatabase> with _$UserDaoMixin {
|
||
UserDao(super.db);
|
||
|
||
// GET operations
|
||
Future<User?> getUserById(String id) {
|
||
return (select(users)..where((u) => u.id.equals(id)))
|
||
.getSingleOrNull();
|
||
}
|
||
|
||
Future<User?> getUserByEmail(String email) {
|
||
return (select(users)..where((u) => u.email.equals(email)))
|
||
.getSingleOrNull();
|
||
}
|
||
|
||
// CREATE operations
|
||
Future<String> createUser(UsersCompanion user) async {
|
||
final inserted = await into(users).insertReturning(user);
|
||
return inserted.id;
|
||
}
|
||
|
||
// UPDATE operations
|
||
Future<bool> updateUser(User user) {
|
||
return update(users).replace(user);
|
||
}
|
||
|
||
Future<void> updateUserPartial(UsersCompanion updates) {
|
||
final userId = updates.id.value;
|
||
return (update(users)..where((u) => u.id.equals(userId)))
|
||
.write(updates);
|
||
}
|
||
|
||
// JOIN queries
|
||
Future<UserWithData?> getUserWithDataById(String id) async {
|
||
final query = select(users).join([
|
||
leftOuterJoin(userDatas, userDatas.userId.equalsExp(users.id)),
|
||
])..where(users.id.equals(id));
|
||
|
||
final result = await query.getSingleOrNull();
|
||
if (result == null) return null;
|
||
|
||
return UserWithData(
|
||
user: result.readTable(users),
|
||
userData: result.readTableOrNull(userDatas),
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
**Ключевые особенности:**
|
||
- ✅ Type-safe запросы (проверяются компилятором)
|
||
- ✅ Абстракция над SQL
|
||
- ✅ Автоматическая обработка транзакций
|
||
- ✅ Поддержка JOIN операций
|
||
|
||
---
|
||
|
||
### 4️⃣ **Domain Models** (Бизнес-логика)
|
||
|
||
**Расположение:** `mnemo_cards_common_backend/lib/src/models/`
|
||
|
||
**Назначение:** Бизнес-модели с логикой приложения
|
||
|
||
**Пример:**
|
||
|
||
```dart
|
||
// mnemo_cards_common_backend/lib/src/models/user/user_model.dart
|
||
class UserModel {
|
||
final String? id;
|
||
final String? name;
|
||
final String? email;
|
||
final bool admin;
|
||
final List<String> purchases;
|
||
final UserSettings? userSettings;
|
||
|
||
// Бизнес-логика
|
||
UserDataModel? userData;
|
||
CardPackModel? subscriptionModel;
|
||
List<CardPackModel> packs = [];
|
||
|
||
// Методы бизнес-логики
|
||
bool get hasActiveSubscription =>
|
||
subscriptionModel != null && subscriptionModel!.isActive;
|
||
|
||
bool canAccessPack(String packId) {
|
||
return packs.any((p) => p.id == packId) || admin;
|
||
}
|
||
}
|
||
```
|
||
|
||
**Конвертация Drift → Domain Model:**
|
||
|
||
```dart
|
||
// lib/user/user_drift_extension.dart
|
||
extension UserToUserModel on User {
|
||
Future<UserModel> toUserModel() async {
|
||
return UserModel(
|
||
id: id,
|
||
name: name,
|
||
email: email,
|
||
admin: admin,
|
||
purchases: purchases,
|
||
userSettings: userSettings != null
|
||
? UserSettings.fromJson(userSettings!)
|
||
: null,
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
**Обратная конвертация (Domain → Drift):**
|
||
|
||
```dart
|
||
extension UserModelToUser on UserModel {
|
||
UsersCompanion toUsersCompanion() {
|
||
return UsersCompanion(
|
||
id: id != null ? Value(id!) : const Value.absent(),
|
||
name: Value(name),
|
||
email: Value(email),
|
||
admin: Value(admin),
|
||
purchases: Value(purchases),
|
||
userSettings: Value(userSettings?.toJson()),
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
**Ключевые особенности:**
|
||
- ✅ Содержат бизнес-логику
|
||
- ✅ Могут иметь связанные объекты (UserData, Packs, etc.)
|
||
- ✅ Независимы от слоя БД
|
||
|
||
---
|
||
|
||
## 🔄 Drift Models vs Domain Models - В чем разница?
|
||
|
||
**Это критически важное различие!** Давайте разберем детально.
|
||
|
||
### 📊 Сравнение
|
||
|
||
| Характеристика | Drift Models (из DAO) | Domain Models |
|
||
|----------------|----------------------|---------------|
|
||
| **Источник** | Генерируются Drift из таблиц БД | Создаются вручную для бизнес-логики |
|
||
| **Соответствие БД** | Точное соответствие структуре таблиц | Может отличаться от структуры БД |
|
||
| **Связанные объекты** | ❌ Нет (только FK в таблицах) | ✅ Да (загружаются отдельно) |
|
||
| **Бизнес-логика** | ❌ Нет | ✅ Да (методы, проверки) |
|
||
| **Где используются** | Только в слое БД (DAO) | В бизнес-логике (Managers, API) |
|
||
| **Изменения** | Автогенерируются при изменении таблиц | Изменяются вручную |
|
||
| **Пример** | `User`, `UserData` (из database.g.dart) | `UserModel`, `UserDataModel` |
|
||
|
||
### 🔍 Детальное сравнение на примере User
|
||
|
||
#### Drift Model: `User` (из DAO)
|
||
|
||
```dart
|
||
// lib/database/database.g.dart (автогенерируется Drift)
|
||
class User extends DataClass implements Insertable<User> {
|
||
final String id;
|
||
final String externalUserId;
|
||
final String? name;
|
||
final String? email;
|
||
final bool admin;
|
||
final String? userSettings;
|
||
final List<String> purchases;
|
||
final PgDateTime createdAt;
|
||
final PgDateTime updatedAt;
|
||
final bool isDeleted;
|
||
|
||
// ❌ НЕТ связанных объектов
|
||
// ❌ НЕТ бизнес-логики
|
||
// ❌ Только данные, точно соответствующие таблице users
|
||
}
|
||
```
|
||
|
||
**Особенности:**
|
||
- ✅ Точное соответствие таблице `users` в PostgreSQL
|
||
- ✅ Все поля из БД присутствуют
|
||
- ❌ Нет связанных объектов (packs, subscriptionModel, userData)
|
||
- ❌ Нет методов бизнес-логики
|
||
- ❌ Используется только для работы с БД
|
||
|
||
**Откуда берется:**
|
||
```dart
|
||
// DAO возвращает Drift Model
|
||
final user = await _db.userDao.getUserById(id); // Returns: User (Drift)
|
||
```
|
||
|
||
#### Domain Model: `UserModel`
|
||
|
||
```dart
|
||
// mnemo_cards_common_backend/lib/src/models/user/user_model.dart
|
||
class UserModel {
|
||
String? id;
|
||
final String? name;
|
||
final String? email;
|
||
final bool admin;
|
||
final List<String> purchases;
|
||
final String? userSettings;
|
||
|
||
// ✅ Связанные объекты (загружаются отдельно)
|
||
final List<CardPackModel> packs = [];
|
||
UserDataModel? userData;
|
||
UserSubscriptionModel? subscriptionModel;
|
||
|
||
// ✅ Может содержать бизнес-логику через extensions
|
||
}
|
||
```
|
||
|
||
**Особенности:**
|
||
- ✅ Может отличаться от структуры БД
|
||
- ✅ Содержит связанные объекты (загружаются отдельно)
|
||
- ✅ Используется для бизнес-логики
|
||
- ✅ Может иметь методы (через extensions)
|
||
- ✅ Независим от структуры БД
|
||
|
||
**Откуда берется:**
|
||
```dart
|
||
// Конвертация Drift → Domain Model
|
||
final user = await _db.userDao.getUserById(id); // User (Drift)
|
||
final userModel = await user.toUserModel(); // UserModel (Domain)
|
||
```
|
||
|
||
### 🔄 Процесс конвертации
|
||
|
||
#### Шаг 1: Получение Drift Model из БД
|
||
|
||
```dart
|
||
// DAO возвращает Drift Model
|
||
final user = await _db.userDao.getUserById(userId);
|
||
// user это: User (Drift Model)
|
||
// Содержит только поля из таблицы users
|
||
// user.id, user.name, user.email, etc.
|
||
// НО: НЕТ user.packs, НЕТ user.subscriptionModel
|
||
```
|
||
|
||
#### Шаг 2: Конвертация в Domain Model
|
||
|
||
```dart
|
||
// lib/user/user_drift_extension.dart
|
||
extension UserToUserModel on User {
|
||
Future<UserModel> toUserModel() async {
|
||
// Создаем Domain Model из Drift Model
|
||
final userModel = UserModel(
|
||
id: id,
|
||
name: name,
|
||
email: email,
|
||
admin: admin,
|
||
purchases: purchases,
|
||
userSettings: userSettings,
|
||
);
|
||
// ⚠️ На этом этапе связанные объекты еще НЕ загружены!
|
||
// packs, userData, subscriptionModel будут null/пустыми
|
||
|
||
return userModel;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Шаг 3: Загрузка связанных объектов (опционально)
|
||
|
||
```dart
|
||
// Если нужны связанные объекты, загружаем их отдельно
|
||
final userModel = await user.toUserModel();
|
||
|
||
// Загружаем паки пользователя
|
||
final userPacks = await _db.userDao.getUserPacks(userId);
|
||
userModel.packs.addAll(userPacks.map((p) => await p.toCardPackModel()));
|
||
|
||
// Загружаем подписку
|
||
final subscription = await _db.subscriptionDao.getActiveSubscription(userId);
|
||
userModel.subscriptionModel = subscription?.toUserSubscriptionModel();
|
||
|
||
// Загружаем userData
|
||
final userData = await _db.userDao.getUserData(userId);
|
||
userModel.userData = await userData?.toUserDataModel();
|
||
```
|
||
|
||
### 💡 Почему нужны оба типа?
|
||
|
||
#### ❌ Если использовать только Drift Models:
|
||
|
||
```dart
|
||
// ❌ Проблема: Нет связанных объектов
|
||
final user = await _db.userDao.getUserById(id);
|
||
|
||
// ❌ Нельзя проверить доступ к паку
|
||
if (user.packs.contains(pack)) { ... } // НЕТ такого поля!
|
||
|
||
// ❌ Нельзя проверить подписку
|
||
if (user.subscriptionModel?.isActive) { ... } // НЕТ такого поля!
|
||
```
|
||
|
||
#### ✅ С Domain Models:
|
||
|
||
```dart
|
||
// ✅ Получаем Domain Model
|
||
final userModel = await _userManager.fetchUser(id);
|
||
|
||
// ✅ Можем работать со связанными объектами
|
||
if (userModel.packs.contains(pack)) { ... } // Работает!
|
||
|
||
// ✅ Можем проверять подписку
|
||
if (userModel.subscriptionModel?.isActive) { ... } // Работает!
|
||
```
|
||
|
||
### 📋 Сравнение на конкретных примерах
|
||
|
||
#### Пример 1: Структура данных
|
||
|
||
**Drift Model (User):**
|
||
```dart
|
||
class User {
|
||
final String id;
|
||
final String name;
|
||
final String email;
|
||
// Только поля из таблицы users
|
||
// НЕТ packs
|
||
// НЕТ subscriptionModel
|
||
// НЕТ userData
|
||
}
|
||
```
|
||
|
||
**Domain Model (UserModel):**
|
||
```dart
|
||
class UserModel {
|
||
final String? id;
|
||
final String? name;
|
||
final String? email;
|
||
// ✅ Может иметь связанные объекты
|
||
final List<CardPackModel> packs = [];
|
||
UserSubscriptionModel? subscriptionModel;
|
||
UserDataModel? userData;
|
||
}
|
||
```
|
||
|
||
#### Пример 2: Использование в коде
|
||
|
||
**С Drift Model:**
|
||
```dart
|
||
// ❌ Ограничено только данными из таблицы
|
||
final user = await _db.userDao.getUserById(id);
|
||
print(user.name); // ✅ Работает
|
||
print(user.packs); // ❌ Нет такого поля
|
||
```
|
||
|
||
**С Domain Model:**
|
||
```dart
|
||
// ✅ Можем использовать связанные объекты
|
||
final userModel = await _userManager.fetchUser(id);
|
||
print(userModel.name); // ✅ Работает
|
||
print(userModel.packs.length); // ✅ Работает
|
||
print(userModel.subscriptionModel); // ✅ Работает
|
||
```
|
||
|
||
#### Пример 3: Бизнес-логика
|
||
|
||
**Drift Model - только данные:**
|
||
```dart
|
||
class User {
|
||
// Только поля, никакой логики
|
||
final bool admin;
|
||
|
||
// ❌ Нет методов бизнес-логики
|
||
}
|
||
```
|
||
|
||
**Domain Model - может иметь логику:**
|
||
```dart
|
||
class UserModel {
|
||
final bool admin;
|
||
final List<CardPackModel> packs = [];
|
||
|
||
// ✅ Можем добавить методы через extensions
|
||
bool canAccessPack(String packId) {
|
||
return packs.any((p) => p.id == packId) || admin;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 🎯 Когда использовать что?
|
||
|
||
#### Используйте Drift Models когда:
|
||
|
||
1. ✅ Работаете напрямую с БД (в DAO)
|
||
2. ✅ Делаете простые CRUD операции
|
||
3. ✅ Нужны только данные из одной таблицы
|
||
4. ✅ Не нужны связанные объекты
|
||
|
||
```dart
|
||
// Пример: Простое обновление
|
||
final user = await _db.userDao.getUserById(id);
|
||
await _db.userDao.updateUser(user.copyWith(name: 'New Name'));
|
||
```
|
||
|
||
#### Используйте Domain Models когда:
|
||
|
||
1. ✅ Реализуете бизнес-логику
|
||
2. ✅ Нужны связанные объекты
|
||
3. ✅ Работаете в Managers или API
|
||
4. ✅ Нужны методы и проверки
|
||
|
||
```dart
|
||
// Пример: Бизнес-логика
|
||
final userModel = await _userManager.fetchUser(id);
|
||
if (userModel.subscriptionModel?.isActive == true) {
|
||
// Логика с подпиской
|
||
}
|
||
```
|
||
|
||
### 🔄 Типичный поток работы
|
||
|
||
```dart
|
||
// 1. DAO возвращает Drift Model (только данные из БД)
|
||
final user = await _db.userDao.getUserById(id); // User (Drift)
|
||
|
||
// 2. Конвертируем в Domain Model (базовая конвертация)
|
||
final userModel = await user.toUserModel(); // UserModel (Domain)
|
||
|
||
// 3. При необходимости загружаем связанные объекты
|
||
if (needFullData) {
|
||
final packs = await _db.userDao.getUserPacks(id);
|
||
userModel.packs.addAll(/* конвертируем packs */);
|
||
|
||
final subscription = await _db.subscriptionDao.getActiveSubscription(id);
|
||
userModel.subscriptionModel = /* конвертируем subscription */;
|
||
}
|
||
|
||
// 4. Используем Domain Model для бизнес-логики
|
||
if (userModel.canAccessPack(packId)) {
|
||
// ...
|
||
}
|
||
|
||
// 5. Конвертируем в DTO для API
|
||
final dto = await userModel.toDto();
|
||
```
|
||
|
||
### 🎓 Ключевые выводы
|
||
|
||
1. **Drift Models** = прямые маппинги строк БД
|
||
- Только данные из таблиц
|
||
- Нет связанных объектов
|
||
- Используются только в слое БД
|
||
|
||
2. **Domain Models** = модели для бизнес-логики
|
||
- Могут иметь связанные объекты
|
||
- Используются в бизнес-логике
|
||
- Независимы от структуры БД
|
||
|
||
3. **Конвертация** всегда идет Drift → Domain
|
||
- DAO возвращает Drift Models
|
||
- Конвертируем в Domain Models через extensions
|
||
- Domain Models используются в остальном коде
|
||
|
||
4. **Разделение ответственности:**
|
||
- **Drift Models** = работа с БД
|
||
- **Domain Models** = бизнес-логика
|
||
- **DTO** = передача данных через API
|
||
|
||
---
|
||
|
||
### 5️⃣ **DTO** (Data Transfer Objects)
|
||
|
||
**Расположение:** `mnemo_cards_common/lib/src/dtos/`
|
||
|
||
**Назначение:** Объекты для передачи данных через API (JSON)
|
||
|
||
**Пример:**
|
||
|
||
```dart
|
||
// mnemo_cards_common/lib/src/dtos/user/user_dto.dart
|
||
@JsonSerializable()
|
||
@CopyWith()
|
||
class UserDto {
|
||
String? id;
|
||
final String? name;
|
||
final String? email;
|
||
final bool admin;
|
||
final List<String> packs;
|
||
final bool? subscription;
|
||
final Set<SubscriptionFeatureEnum> subscriptionFeatures;
|
||
final UserDataDto? userDataDto;
|
||
|
||
UserDto({
|
||
this.id,
|
||
this.name,
|
||
this.email,
|
||
this.admin = false,
|
||
this.packs = const [],
|
||
this.subscription = false,
|
||
this.subscriptionFeatures = const {},
|
||
this.userDataDto,
|
||
});
|
||
|
||
// JSON сериализация
|
||
factory UserDto.fromJson(Map<String, dynamic> json) =>
|
||
_$UserDtoFromJson(json);
|
||
|
||
Map<String, Object?> toJson() => _$UserDtoToJson(this);
|
||
}
|
||
```
|
||
|
||
**Конвертация Domain Model → DTO:**
|
||
|
||
```dart
|
||
// lib/user/user_model.dart
|
||
extension UserModelExtension on UserModel {
|
||
Future<UserDto> toDto() async {
|
||
final activeSubscription = subscriptionModel != null
|
||
&& subscriptionModel!.isActive;
|
||
|
||
return UserDto(
|
||
id: id,
|
||
name: name,
|
||
email: email,
|
||
admin: admin,
|
||
packs: packs.map((e) => e.id?.toString())
|
||
.whereNotNull()
|
||
.toList(),
|
||
subscription: activeSubscription,
|
||
subscriptionFeatures: subscriptionModel?.features.toSet() ?? {},
|
||
userDataDto: userData?.toDto(),
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
**Ключевые особенности:**
|
||
- ✅ Только данные (no logic)
|
||
- ✅ JSON сериализуемые
|
||
- ✅ Могут отличаться от структуры БД
|
||
- ✅ Версионирование API через DTO
|
||
|
||
---
|
||
|
||
## 🤔 Зачем нужны Domain Models, если есть DTO?
|
||
|
||
**Это частый вопрос!** Давайте разберемся на конкретных примерах из кода.
|
||
|
||
### ❌ Почему нельзя использовать только DTO?
|
||
|
||
#### Проблема 1: **DTO не содержат связанные объекты**
|
||
|
||
**UserModel (Domain):**
|
||
```dart
|
||
class UserModel {
|
||
UserSubscriptionModel? subscriptionModel; // ✅ Полный объект подписки
|
||
List<CardPackModel> packs = []; // ✅ Полные объекты паков
|
||
UserDataModel? userData; // ✅ Полный объект данных
|
||
}
|
||
```
|
||
|
||
**UserDto:**
|
||
```dart
|
||
class UserDto {
|
||
bool? subscription; // ❌ Только boolean
|
||
Set<SubscriptionFeatureEnum> subscriptionFeatures; // ❌ Только фичи
|
||
List<String> packs; // ❌ Только ID строки
|
||
UserDataDto? userDataDto; // ❌ Упрощенная версия
|
||
}
|
||
```
|
||
|
||
#### Проблема 2: **Внутри backend нужна бизнес-логика**
|
||
|
||
**Пример из реального кода (`lib/packs/pack_dto_converter.dart`):**
|
||
|
||
```dart
|
||
Future<CardPackPreviewDto> toCardPackPreviewDto(
|
||
CardPackModel model,
|
||
UserModel? userModel, // ← Domain Model!
|
||
) async {
|
||
// Проверка доступа через связанные объекты
|
||
bool available = model.users.contains(userModel);
|
||
|
||
if (userModel != null && !available) {
|
||
// Используем subscriptionModel с методами
|
||
available = userModel.subscriptionModel?.features
|
||
.contains(SubscriptionFeatureEnum.packs) == true;
|
||
}
|
||
|
||
// Вычисляем цену через UserModel
|
||
String? price = model.price;
|
||
if (userModel != null && !available) {
|
||
price = await _productsPriceResolver.userPackPrice(userModel, model);
|
||
}
|
||
|
||
// ...
|
||
}
|
||
```
|
||
|
||
**С DTO это невозможно:**
|
||
```dart
|
||
// ❌ Невозможно - DTO не имеет subscriptionModel
|
||
available = userDto.subscriptionModel?.features... // Нет такого поля!
|
||
|
||
// ❌ Невозможно - DTO содержит только ID паков
|
||
userDto.packs.contains(model) // packs это List<String>, не объекты!
|
||
```
|
||
|
||
#### Проблема 3: **DTO уже вычислены и упрощены**
|
||
|
||
**При создании DTO (`lib/user/user_model.dart`):**
|
||
|
||
```dart
|
||
extension UserModelExtension on UserModel {
|
||
Future<UserDto> toDto() async {
|
||
// Вычисляем активность подписки из Domain Model
|
||
final activeSubscription = subscriptionModel != null
|
||
&& subscriptionModel!.isActive; // ← Используем Domain Model!
|
||
|
||
// Извлекаем только ID из паков
|
||
final packIds = packs.map((e) => e.id?.toString())
|
||
.whereNotNull()
|
||
.toList(); // ← Упрощаем список объектов
|
||
|
||
return UserDto(
|
||
subscription: activeSubscription, // Предвычисленное значение
|
||
packs: packIds, // Только строки
|
||
subscriptionFeatures: subscriptionModel?.features.toSet() ?? {},
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
**DTO - это "моментальный снимок" состояния Domain Model для клиента.**
|
||
|
||
### ✅ Правильное использование
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Backend Business Logic │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ Domain Models (UserModel) │ │
|
||
│ │ - Связанные объекты (subscriptionModel, packs) │ │
|
||
│ │ - Бизнес-логика │ │
|
||
│ │ - Методы и проверки │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ ↕ (toDto()) │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ DTO (UserDto) │ │
|
||
│ │ - Только примитивы │ │
|
||
│ │ - Предвычисленные значения │ │
|
||
│ │ - Упрощенная структура │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ ↕ (toJson()) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
JSON Response
|
||
↓
|
||
Client App
|
||
```
|
||
|
||
### 📊 Сравнение на практике
|
||
|
||
| Задача | Domain Model (UserModel) | DTO (UserDto) |
|
||
|--------|-------------------------|---------------|
|
||
| **Проверить доступ к паку** | ✅ `user.packs.contains(pack)` | ❌ Нет объектов паков, только ID |
|
||
| **Проверить активную подписку** | ✅ `user.subscriptionModel?.isActive` | ❌ Только boolean `subscription` |
|
||
| **Получить фичи подписки** | ✅ `user.subscriptionModel?.features` | ✅ `userDto.subscriptionFeatures` |
|
||
| **Вычислить цену с учетом скидок** | ✅ Использует `user.userData` | ❌ Нет userData для логики |
|
||
| **Отправить через API** | ❌ Слишком сложная структура | ✅ Упрощенная структура |
|
||
| **JSON сериализация** | ❌ Может содержать циклические ссылки | ✅ Безопасная сериализация |
|
||
|
||
### 💡 Реальные примеры из кода
|
||
|
||
#### Пример 1: Проверка доступа через подписку
|
||
|
||
```dart
|
||
// ✅ С Domain Model - работает
|
||
// lib/packs/pack_dto_converter.dart
|
||
bool canAccess = userModel.subscriptionModel?.features
|
||
.contains(SubscriptionFeatureEnum.packs) == true;
|
||
|
||
// ❌ С DTO - невозможно (нет subscriptionModel)
|
||
// Можно только проверить subscriptionFeatures, но логика сложнее
|
||
```
|
||
|
||
#### Пример 2: Вычисление цены со скидкой
|
||
|
||
```dart
|
||
// ✅ С Domain Model - используем userData для скидок
|
||
// lib/packs/products_price_resolver.dart
|
||
Future<String> userPackPrice(
|
||
UserModel userModel, // Domain Model
|
||
CardPackModel model,
|
||
) async {
|
||
if (userModel.id != null) {
|
||
final userData = await _db.userDao.getUserData(userModel.id!);
|
||
final maxDiscount = await _discountsManager.getProductDiscount(
|
||
model,
|
||
userData, // Используем UserDataModel для логики
|
||
);
|
||
// ... вычисление скидки
|
||
}
|
||
}
|
||
|
||
// ❌ С DTO - нет доступа к userData для вычислений
|
||
```
|
||
|
||
#### Пример 3: Конвертация в DTO использует Domain Model
|
||
|
||
```dart
|
||
// Этот код находится ВНУТРИ backend и использует Domain Model
|
||
extension UserModelExtension on UserModel {
|
||
Future<UserDto> toDto() async {
|
||
// Используем Domain Model для вычислений
|
||
final activeSubscription = subscriptionModel != null
|
||
&& subscriptionModel!.isActive;
|
||
|
||
// Извлекаем данные из связанных объектов
|
||
final packIds = packs.map((e) => e.id?.toString())
|
||
.whereNotNull()
|
||
.toList();
|
||
|
||
// Создаем упрощенный DTO для клиента
|
||
return UserDto(
|
||
subscription: activeSubscription, // Предвычисленное
|
||
packs: packIds, // Упрощенное
|
||
subscriptionFeatures: subscriptionModel?.features.toSet() ?? {},
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 🎯 Вывод
|
||
|
||
**Domain Models нужны для:**
|
||
|
||
1. ✅ **Бизнес-логики внутри backend**
|
||
- Проверки доступа
|
||
- Вычисления цен
|
||
- Валидация данных
|
||
- Работа со связанными объектами
|
||
|
||
2. ✅ **Работы со сложными структурами**
|
||
- Связанные объекты (subscriptionModel, packs, userData)
|
||
- Методы и computed properties
|
||
- Циклические связи
|
||
|
||
3. ✅ **Независимости от API**
|
||
- Domain Models не зависят от формата API
|
||
- Можно менять API без изменения бизнес-логики
|
||
- Переиспользование в разных контекстах
|
||
|
||
**DTO нужны для:**
|
||
|
||
1. ✅ **Передачи данных через API**
|
||
- Упрощенная структура
|
||
- Только примитивы
|
||
- Без циклических ссылок
|
||
|
||
2. ✅ **Версионирования API**
|
||
- Можно менять DTO без изменения Domain Models
|
||
- Обратная совместимость
|
||
|
||
3. ✅ **Оптимизации**
|
||
- Отправляем только нужные данные
|
||
- Предвычисленные значения
|
||
|
||
### 🔄 Типичный поток
|
||
|
||
```dart
|
||
// 1. Получаем Domain Model из БД
|
||
final user = await _userManager.fetchUser(userId); // UserModel
|
||
|
||
// 2. Используем Domain Model для бизнес-логики
|
||
if (user.subscriptionModel?.isActive == true) {
|
||
// Логика с использованием subscriptionModel
|
||
}
|
||
|
||
// 3. Конвертируем в DTO для API
|
||
final dto = await user.toDto(); // UserDto
|
||
|
||
// 4. Возвращаем JSON клиенту
|
||
return Response.ok(dto.toJson());
|
||
```
|
||
|
||
**Внутри backend работаем с Domain Models, клиенту отправляем DTO!** 🎯
|
||
|
||
---
|
||
|
||
## 🤔 Зачем нужны Domain Models, если есть DTO?
|
||
|
||
**Это частый вопрос!** Давайте разберемся на конкретных примерах.
|
||
|
||
### ❌ Почему нельзя использовать только DTO?
|
||
|
||
#### Проблема 1: **DTO не содержат связанные объекты**
|
||
|
||
**UserModel (Domain):**
|
||
```dart
|
||
class UserModel {
|
||
UserSubscriptionModel? subscriptionModel; // ✅ Полный объект подписки
|
||
List<CardPackModel> packs = []; // ✅ Полные объекты паков
|
||
UserDataModel? userData; // ✅ Полный объект данных
|
||
}
|
||
```
|
||
|
||
**UserDto:**
|
||
```dart
|
||
class UserDto {
|
||
bool? subscription; // ❌ Только boolean
|
||
Set<SubscriptionFeatureEnum> subscriptionFeatures; // ❌ Только фичи
|
||
List<String> packs; // ❌ Только ID строки
|
||
UserDataDto? userDataDto; // ❌ Упрощенная версия
|
||
}
|
||
```
|
||
|
||
#### Проблема 2: **Внутри backend нужна бизнес-логика**
|
||
|
||
**Пример из реального кода:**
|
||
|
||
```dart
|
||
// lib/packs/pack_dto_converter.dart
|
||
Future<CardPackPreviewDto> toCardPackPreviewDto(
|
||
CardPackModel model,
|
||
UserModel? userModel, // ← Domain Model!
|
||
) async {
|
||
// Проверка доступа через связанные объекты
|
||
bool available = model.users.contains(userModel);
|
||
|
||
if (userModel != null && !available) {
|
||
// Используем subscriptionModel с методами
|
||
available = userModel.subscriptionModel?.features
|
||
.contains(SubscriptionFeatureEnum.packs) == true;
|
||
}
|
||
|
||
// Вычисляем цену через UserModel
|
||
String? price = model.price;
|
||
if (userModel != null && !available) {
|
||
price = await _productsPriceResolver.userPackPrice(userModel, model);
|
||
}
|
||
|
||
// ...
|
||
}
|
||
```
|
||
|
||
**С DTO это невозможно:**
|
||
```dart
|
||
// ❌ Невозможно - DTO не имеет subscriptionModel
|
||
available = userDto.subscriptionModel?.features... // Нет такого поля!
|
||
|
||
// ❌ Невозможно - DTO содержит только ID паков
|
||
userDto.packs.contains(model) // packs это List<String>, не объекты!
|
||
```
|
||
|
||
#### Проблема 3: **DTO уже вычислены и упрощены**
|
||
|
||
**При создании DTO:**
|
||
|
||
```dart
|
||
extension UserModelExtension on UserModel {
|
||
Future<UserDto> toDto() async {
|
||
// Вычисляем активность подписки
|
||
final activeSubscription = subscriptionModel != null
|
||
&& subscriptionModel!.isActive; // ← Используем Domain Model!
|
||
|
||
// Извлекаем только ID из паков
|
||
final packIds = packs.map((e) => e.id?.toString())
|
||
.whereNotNull()
|
||
.toList(); // ← Упрощаем список объектов
|
||
|
||
return UserDto(
|
||
subscription: activeSubscription, // Предвычисленное значение
|
||
packs: packIds, // Только строки
|
||
subscriptionFeatures: subscriptionModel?.features.toSet() ?? {},
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
**DTO - это "моментальный снимок" состояния Domain Model для клиента.**
|
||
|
||
### ✅ Правильное использование
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Backend Business Logic │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ Domain Models (UserModel) │ │
|
||
│ │ - Связанные объекты (subscriptionModel, packs) │ │
|
||
│ │ - Бизнес-логика │ │
|
||
│ │ - Методы и проверки │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ ↕ (toDto()) │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ DTO (UserDto) │ │
|
||
│ │ - Только примитивы │ │
|
||
│ │ - Предвычисленные значения │ │
|
||
│ │ - Упрощенная структура │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ ↕ (toJson()) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
JSON Response
|
||
↓
|
||
Client App
|
||
```
|
||
|
||
### 📊 Сравнение на практике
|
||
|
||
| Задача | Domain Model (UserModel) | DTO (UserDto) |
|
||
|--------|-------------------------|---------------|
|
||
| **Проверить доступ к паку** | ✅ `user.packs.contains(pack)` | ❌ Нет объектов паков, только ID |
|
||
| **Проверить активную подписку** | ✅ `user.subscriptionModel?.isActive` | ❌ Только boolean `subscription` |
|
||
| **Получить фичи подписки** | ✅ `user.subscriptionModel?.features` | ✅ `userDto.subscriptionFeatures` |
|
||
| **Вычислить цену с учетом скидок** | ✅ Использует `user.userData` | ❌ Нет userData для логики |
|
||
| **Отправить через API** | ❌ Слишком сложная структура | ✅ Упрощенная структура |
|
||
| **JSON сериализация** | ❌ Может содержать циклические ссылки | ✅ Безопасная сериализация |
|
||
|
||
### 💡 Реальные примеры из кода
|
||
|
||
#### Пример 1: Проверка доступа через подписку
|
||
|
||
```dart
|
||
// ✅ С Domain Model - работает
|
||
bool canAccess = userModel.subscriptionModel?.features
|
||
.contains(SubscriptionFeatureEnum.packs) == true;
|
||
|
||
// ❌ С DTO - невозможно (нет subscriptionModel)
|
||
// Можно только проверить subscriptionFeatures, но логика сложнее
|
||
```
|
||
|
||
#### Пример 2: Вычисление цены со скидкой
|
||
|
||
```dart
|
||
// ✅ С Domain Model - используем userData для скидок
|
||
Future<String> userPackPrice(
|
||
UserModel userModel, // Domain Model
|
||
CardPackModel model,
|
||
) async {
|
||
if (userModel.id != null) {
|
||
final userData = await _db.userDao.getUserData(userModel.id!);
|
||
final maxDiscount = await _discountsManager.getProductDiscount(
|
||
model,
|
||
userData, // Используем UserDataModel для логики
|
||
);
|
||
// ... вычисление скидки
|
||
}
|
||
}
|
||
|
||
// ❌ С DTO - нет доступа к userData для вычислений
|
||
```
|
||
|
||
#### Пример 3: Конвертация в DTO использует Domain Model
|
||
|
||
```dart
|
||
// Этот код находится ВНУТРИ backend и использует Domain Model
|
||
extension UserModelExtension on UserModel {
|
||
Future<UserDto> toDto() async {
|
||
// Используем Domain Model для вычислений
|
||
final activeSubscription = subscriptionModel != null
|
||
&& subscriptionModel!.isActive;
|
||
|
||
// Извлекаем данные из связанных объектов
|
||
final packIds = packs.map((e) => e.id?.toString())
|
||
.whereNotNull()
|
||
.toList();
|
||
|
||
// Создаем упрощенный DTO для клиента
|
||
return UserDto(
|
||
subscription: activeSubscription, // Предвычисленное
|
||
packs: packIds, // Упрощенное
|
||
subscriptionFeatures: subscriptionModel?.features.toSet() ?? {},
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 🎯 Вывод
|
||
|
||
**Domain Models нужны для:**
|
||
|
||
1. ✅ **Бизнес-логики внутри backend**
|
||
- Проверки доступа
|
||
- Вычисления цен
|
||
- Валидация данных
|
||
- Работа со связанными объектами
|
||
|
||
2. ✅ **Работы со сложными структурами**
|
||
- Связанные объекты (subscriptionModel, packs, userData)
|
||
- Методы и computed properties
|
||
- Циклические связи
|
||
|
||
3. ✅ **Независимости от API**
|
||
- Domain Models не зависят от формата API
|
||
- Можно менять API без изменения бизнес-логики
|
||
- Переиспользование в разных контекстах
|
||
|
||
**DTO нужны для:**
|
||
|
||
1. ✅ **Передачи данных через API**
|
||
- Упрощенная структура
|
||
- Только примитивы
|
||
- Без циклических ссылок
|
||
|
||
2. ✅ **Версионирования API**
|
||
- Можно менять DTO без изменения Domain Models
|
||
- Обратная совместимость
|
||
|
||
3. ✅ **Оптимизации**
|
||
- Отправляем только нужные данные
|
||
- Предвычисленные значения
|
||
|
||
### 🔄 Типичный поток
|
||
|
||
```dart
|
||
// 1. Получаем Domain Model из БД
|
||
final user = await _userManager.fetchUser(userId); // UserModel
|
||
|
||
// 2. Используем Domain Model для бизнес-логики
|
||
if (user.subscriptionModel?.isActive == true) {
|
||
// Логика с использованием subscriptionModel
|
||
}
|
||
|
||
// 3. Конвертируем в DTO для API
|
||
final dto = await user.toDto(); // UserDto
|
||
|
||
// 4. Возвращаем JSON клиенту
|
||
return Response.ok(dto.toJson());
|
||
```
|
||
|
||
**Внутри backend работаем с Domain Models, клиенту отправляем DTO!** 🎯
|
||
|
||
---
|
||
|
||
### 6️⃣ **API Layer** (HTTP Endpoints)
|
||
|
||
**Расположение:** `lib/api/v2/*_api_v2.dart`
|
||
|
||
**Назначение:** HTTP endpoints, которые возвращают JSON
|
||
|
||
**Пример:**
|
||
|
||
```dart
|
||
// lib/api/v2/users_api_v2.dart
|
||
@lazySingleton
|
||
class UsersApiV2 {
|
||
final UserManager _userManager;
|
||
final AppDatabase _db;
|
||
|
||
@Route.get('/users/me')
|
||
Future<Response> getCurrentUser(Request request) async {
|
||
final user = request.user; // UserModel (domain)
|
||
if (user == null) {
|
||
return _unauthorized();
|
||
}
|
||
|
||
// Конвертация: UserModel → UserDto
|
||
final dto = await user.toDto();
|
||
|
||
// Конвертация: UserDto → JSON
|
||
return _json(dto.toJson());
|
||
}
|
||
|
||
@Route('PATCH', '/users/me')
|
||
Future<Response> updateCurrentUser(Request request) async {
|
||
final user = request.user;
|
||
final body = jsonDecode(await request.readAsString());
|
||
|
||
// Обновление через DAO
|
||
await _db.userDao.updateUserPartial(
|
||
UsersCompanion(
|
||
id: Value(user.id!),
|
||
name: body['name'] != null
|
||
? Value(body['name'])
|
||
: const Value.absent(),
|
||
email: body['email'] != null
|
||
? Value(body['email'])
|
||
: const Value.absent(),
|
||
updatedAt: Value(PgDateTime(DateTime.now())),
|
||
),
|
||
);
|
||
|
||
// Возврат обновленных данных
|
||
final refreshedUser = await _userManager.fetchUser(user.id!);
|
||
final dto = await refreshedUser.toDto();
|
||
return _json(dto.toJson());
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 Полный цикл: Создание пользователя
|
||
|
||
```dart
|
||
// 1. HTTP Request
|
||
POST /api/v2/auth/register
|
||
{ "email": "test@example.com", "password": "secret123" }
|
||
|
||
// 2. API Handler (auth_api_v2.dart)
|
||
final userModel = await _userManager.createUser(email, password);
|
||
|
||
// 3. UserManager (user_manager.dart)
|
||
Future<UserModel> createUser(String email, String password) async {
|
||
// Создание Drift Companion для insert
|
||
final companion = UsersCompanion.insert(
|
||
externalUserId: generateId(),
|
||
email: email,
|
||
// ...
|
||
);
|
||
|
||
// 4. DAO Insert (user_dao.dart)
|
||
final userId = await _db.userDao.createUser(companion);
|
||
|
||
// 5. Получение созданного User (Drift model)
|
||
final user = await _db.userDao.getUserById(userId);
|
||
|
||
// 6. Конвертация User → UserModel
|
||
return await user!.toUserModel();
|
||
}
|
||
|
||
// 7. API Response: UserModel → UserDto → JSON
|
||
final dto = await userModel.toDto();
|
||
return Response.ok(dto.toJson());
|
||
```
|
||
|
||
**Что происходит в БД:**
|
||
|
||
```sql
|
||
-- Drift автоматически генерирует SQL:
|
||
INSERT INTO users (id, external_user_id, email, created_at, updated_at)
|
||
VALUES (
|
||
gen_random_uuid()::text, -- auto-generated UUID
|
||
'generated-id-123',
|
||
'test@example.com',
|
||
NOW(),
|
||
NOW()
|
||
)
|
||
RETURNING *;
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 Сравнительная таблица
|
||
|
||
| Компонент | Расположение | Тип данных | Назначение | Жизненный цикл |
|
||
|-----------|--------------|------------|------------|----------------|
|
||
| **Tables** | `lib/database/tables/` | Class extends `Table` | Определение схемы БД | Статичен (изменяется миграциями) |
|
||
| **Models (Drift)** | `lib/database/database.g.dart` | Immutable `DataClass` | Данные из БД | Генерируется Drift |
|
||
| **DAO** | `lib/database/daos/` | Methods | CRUD операции | Статичен |
|
||
| **Domain Models** | `mnemo_cards_common_backend/models/` | Classes with logic | Бизнес-логика | Может содержать состояние |
|
||
| **DTO** | `mnemo_cards_common/dtos/` | JSON-serializable | API responses | Версионируется |
|
||
| **API** | `lib/api/v2/` | HTTP handlers | Endpoints | Обрабатывает запросы |
|
||
|
||
---
|
||
|
||
## 🔑 Ключевые принципы
|
||
|
||
### 1. **Разделение ответственности**
|
||
|
||
- **Tables** → Определяют структуру БД
|
||
- **Drift Models** → Представляют данные из БД
|
||
- **DAO** → Абстракция над SQL запросами
|
||
- **Domain Models** → Содержат бизнес-логику
|
||
- **DTO** → Для передачи данных через API
|
||
- **API** → HTTP endpoints
|
||
|
||
### 2. **Направление конвертации**
|
||
|
||
```
|
||
Drift Model (User)
|
||
→ Domain Model (UserModel) [через extension]
|
||
→ DTO (UserDto) [через toDto()]
|
||
→ JSON [через toJson()]
|
||
```
|
||
|
||
### 3. **Type Safety**
|
||
|
||
Все преобразования типизированы на уровне компилятора:
|
||
- ✅ Drift проверяет запросы к БД
|
||
- ✅ Dart проверяет конвертации
|
||
- ✅ JSON сериализация с кодогенерацией
|
||
|
||
### 4. **Независимость слоев**
|
||
|
||
- **Domain Models** не зависят от БД
|
||
- **DTO** не зависят от Domain Models (но конвертируются из них)
|
||
- **API** использует Domain Models и DTO
|
||
|
||
---
|
||
|
||
## 💡 Практические примеры
|
||
|
||
### Пример 1: Получение пользователя с данными
|
||
|
||
```dart
|
||
// DAO возвращает User (Drift) + UserData (Drift)
|
||
final userWithData = await _db.userDao.getUserWithDataById(userId);
|
||
|
||
// Конвертация в Domain Models
|
||
final userModel = await userWithData.user.toUserModel();
|
||
final userDataModel = userWithData.userData?.toUserDataModel();
|
||
|
||
// Связывание
|
||
userModel.userData = userDataModel;
|
||
|
||
// Конвертация в DTO для API
|
||
final dto = await userModel.toDto(); // Включает userDataDto
|
||
```
|
||
|
||
### Пример 2: Создание записи с транзакцией
|
||
|
||
```dart
|
||
// Использование Companion для insert
|
||
await _db.transaction(() async {
|
||
// Создать пользователя
|
||
final userCompanion = UsersCompanion.insert(
|
||
externalUserId: 'telegram_123',
|
||
name: 'John Doe',
|
||
);
|
||
final userId = await _db.userDao.createUser(userCompanion);
|
||
|
||
// Создать UserData
|
||
final userDataCompanion = UserDatasCompanion.insert(
|
||
userId: userId,
|
||
totalStudyTimeMinutes: 0,
|
||
);
|
||
await _db.userDao.createUserData(userDataCompanion);
|
||
});
|
||
```
|
||
|
||
### Пример 3: Обновление частичных данных
|
||
|
||
```dart
|
||
// Использование Companion для partial update
|
||
await _db.userDao.updateUserPartial(
|
||
UsersCompanion(
|
||
id: Value(userId),
|
||
name: Value('New Name'), // Обновить только name
|
||
// email остается без изменений (Value.absent())
|
||
updatedAt: Value(PgDateTime(DateTime.now())),
|
||
),
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 Итоги
|
||
|
||
### Связи:
|
||
|
||
1. **Tables** → определяют структуру БД
|
||
2. **Drift Models** → автогенерируются из Tables
|
||
3. **DAO** → используют Drift Models для работы с БД
|
||
4. **Domain Models** → конвертируются из Drift Models через extensions
|
||
5. **DTO** → конвертируются из Domain Models через toDto()
|
||
6. **API** → используют Domain Models и возвращают DTO как JSON
|
||
|
||
### Преимущества этой архитектуры:
|
||
|
||
✅ **Type Safety** - все проверяется компилятором
|
||
✅ **Separation of Concerns** - каждый слой решает свою задачу
|
||
✅ **Maintainability** - легко изменять отдельные слои
|
||
✅ **Testability** - можно мокировать любой слой
|
||
✅ **Scalability** - легко добавлять новые сущности
|
||
|
||
---
|
||
|
||
**Этот документ должен помочь понять, как данные проходят через все слои приложения!** 🚀
|