بخش چهارم — پروژه قیمت‌بان

درس بیست‌ویکم

وقتی کاربر روی دکمه ثبت‌نام می‌زنه، پشت صحنه چه اتفاقی می‌افته؟

ثبت‌نام کسب‌وکار

تا اینجا بیشتر درباره قطعات معماری برنامه حرف زدیم. Retrofit رو شناختیم، ViewModel و Repository رو دیدیم، درباره State، Session و Token هم صحبت کردیم. حالا وقتشه این قطعات رو برای اولین‌بار کنار هم قرار بدیم و یک فرایند واقعی بسازیم: ثبت‌نام یک کسب‌وکار در قیمت‌بان.

در نسخه وب، احتمالاً یک فرم HTML می‌ساختی، اطلاعات رو با JavaScript یا ارسال معمولی فرم به سرور می‌فرستادی و بعد براساس پاسخ سرور، کاربر رو وارد صفحه بعد می‌کردی. در اندروید هم اصل ماجرا همینه، اما چون معماری برنامه چندلایه است، اطلاعات قرار نیست مستقیماً از دکمه ثبت‌نام به Retrofit برسن. هر بخش باید مسئولیت مشخص خودش رو انجام بده.

فرض کن کاربر نام کسب‌وکار، شماره موبایل و رمز عبورش رو وارد می‌کنه و روی دکمه ثبت‌نام می‌زنه. صفحه فقط باید این اطلاعات رو جمع کنه و به ViewModel تحویل بده. ViewModel وضعیت ثبت‌نام رو مدیریت می‌کنه، Repository درخواست رو به سرور می‌فرسته، پاسخ رو بررسی می‌کنه و در صورت موفقیت، Token رو ذخیره می‌کنه. بعد ViewModel به صفحه خبر میده که ثبت‌نام موفق بوده و صفحه کاربر رو وارد بخش اصلی برنامه می‌کنه.

مسیر کلی این اتفاق به این صورته:

RegisterScreen
↓
RegisterViewModel
↓
AuthRepository
↓
AuthApi
↓
Server
↓
Access Token
↓
TokenStorage
↓
Home

این نمودار شاید ساده به نظر برسه، اما تقریباً همه مفاهیمی که در درس‌های قبلی یاد گرفتیم، داخلش حضور دارن.

فرم ثبت‌نام چه اطلاعاتی رو نگه می‌داره؟

در Compose، هر کادر ورودی باید یک State داشته باشه تا مقدار فعلی اون نگهداری بشه. لازم نیست کل ظاهر فرم رو بنویسیم. چیزی که در این درس اهمیت داره، نحوه نگهداری اطلاعاتیه که قراره برای ثبت‌نام ارسال بشن.

var businessName by remember { mutableStateOf("") }
var phone by remember { mutableStateOf("") }
var password by remember { mutableStateOf("") }

var businessName by remember { mutableStateOf("") }
var phone by remember { mutableStateOf("") }
var password by remember { mutableStateOf("") }

هر متغیر، مقدار یکی از فیلدهای فرم رو نگه می‌داره. مقدار اولیه "" یعنی در شروع، فیلد خالیه. وقتی کاربر داخل TextField چیزی می‌نویسه، مقدار همین متغیر تغییر می‌کنه و Compose هم بخش مربوط به صفحه رو دوباره به‌روزرسانی می‌کنه.

در اینجا از remember استفاده کردیم، چون اطلاعات فقط به خود فرم تعلق دارن. اما یک نکته مهم وجود داره: اگر صفحه به دلیل تغییر تنظیمات یا بازسازی Activity دوباره ساخته بشه، remember ممکنه مقدارها رو از دست بده. برای فرم‌های مهم، معمولاً میشه از rememberSaveable استفاده کرد:

var businessName by rememberSaveable { mutableStateOf("") }

var businessName by rememberSaveable { mutableStateOf("") }

rememberSaveable شبیه remember عمل می‌کنه، اما مقدارهای ساده‌ای مثل متن رو در بازسازی صفحه هم حفظ می‌کنه. بنابراین اگر صفحه موقتاً دوباره ساخته شد، چیزی که کاربر نوشته ناپدید نمیشه.

قرار نیست همه Stateهای برنامه داخل ViewModel قرار بگیرن. متن موقتی که کاربر داخل فیلد نوشته، می‌تونه داخل خود صفحه باقی بمونه. اما وضعیت اصلی فرایند، مثل در حال ارسال بودن، موفقیت یا خطا، بهتره داخل ViewModel مدیریت بشه.

کلیک روی دکمه ثبت‌نام

وقتی کاربر روی دکمه می‌زنه، صفحه نباید خودش Retrofit رو صدا بزنه یا Token رو ذخیره کنه. صفحه فقط داده‌ها رو تحویل ViewModel میده:

viewModel.register(
    businessName = businessName.trim(),
    phone = phone.trim(),
    password = password
)

viewModel.register(
    businessName = businessName.trim(),
    phone = phone.trim(),
    password = password
)

اینجا چند نکته وجود داره. اول اینکه صفحه مقادیر فعلی فرم رو برای ViewModel می‌فرسته. دوم اینکه برای نام کسب‌وکار و شماره موبایل از trim استفاده کردیم تا فاصله‌های ناخواسته ابتدا و انتهای متن حذف بشن. مثلاً اگر کاربر بعد از شماره موبایل یک فاصله وارد کرده باشه، همون فاصله نباید به سرور ارسال بشه.

برای رمز عبور الزاماً از trim استفاده نکردیم، چون فاصله ممکنه واقعاً بخشی از رمز انتخاب‌شده باشه. البته تصمیم نهایی به قوانین پروژه بستگی داره. بعضی برنامه‌ها اصلاً اجازه استفاده از فاصله در رمز رو نمیدن و این موضوع رو در اعتبارسنجی کنترل می‌کنن.

مهم‌ترین نکته اینه که صفحه فقط میگه: کاربر این اطلاعات رو وارد کرده و درخواست ثبت‌نام داره. صفحه نمی‌دونه این درخواست چطور انجام میشه و نتیجه از چه مسیری برمی‌گرده.

اعتبارسنجی در کجا انجام میشه؟

قبل از ارسال درخواست، باید بررسی کنیم که اطلاعات اولیه معتبر باشن. مثلاً نام کسب‌وکار خالی نباشه، شماره موبایل ساختار قابل قبولی داشته باشه و رمز عبور بیش از حد کوتاه نباشه.

اعتبارسنجی ساده رو میشه قبل از ورود به Repository و داخل ViewModel انجام داد:

if (businessName.isBlank()) {
    showError("نام کسب‌وکار رو وارد کن")
    return
}

if (businessName.isBlank()) {
    showError("نام کسب‌وکار رو وارد کن")
    return
}

isBlank فقط خالی بودن متن رو بررسی نمی‌کنه؛ متنی رو که فقط از فاصله تشکیل شده هم خالی در نظر می‌گیره. مثلاً ” ” از نظر isBlank یک مقدار نامعتبره. دستور return هم باعث میشه اجرای تابع در همین نقطه متوقف بشه. یعنی وقتی نام کسب‌وکار وارد نشده، درخواست بیهوده‌ای به سرور فرستاده نمیشه.

برای رمز عبور هم می‌تونیم یک قانون اولیه داشته باشیم:

if (password.length < 8) {
    showError("رمز عبور باید حداقل ۸ کاراکتر باشه")
    return
}

if (password.length < 8) {
    showError("رمز عبور باید حداقل ۸ کاراکتر باشه")
    return
}

این اعتبارسنجی برای تجربه کاربریه. یعنی به جای اینکه درخواست به سرور بره و بعد سرور خطا برگردونه، برنامه سریعاً مشکل رو به کاربر میگه.

اما اعتبارسنجی داخل اپلیکیشن به این معنی نیست که سرور دیگه نباید اطلاعات رو بررسی کنه. کاربر می‌تونه نسخه دست‌کاری‌شده‌ای از برنامه داشته باشه یا اصلاً درخواست رو از ابزار دیگه‌ای برای API بفرسته. بنابراین قوانین مهم باید دوباره در سمت سرور هم بررسی بشن. اپلیکیشن برای سرعت و تجربه کاربری اعتبارسنجی می‌کنه؛ سرور برای امنیت و حفظ صحت اطلاعات.

مدل درخواست ثبت‌نام

سرور معمولاً انتظار داره اطلاعات ثبت‌نام رو در قالب JSON دریافت کنه. مثلاً:

{
  "business_name": "فروشگاه مرکزی",
  "phone": "09121234567",
  "password": "12345678"
}

{
  "business_name": "فروشگاه مرکزی",
  "phone": "09121234567",
  "password": "12345678"
}

برای ساختن چنین JSONای، یک مدل درخواست تعریف می‌کنیم:

data class RegisterRequest(
    val businessName: String,
    val phone: String,
    val password: String
)

data class RegisterRequest(
    val businessName: String,
    val phone: String,
    val password: String
)

این کلاس فقط یک ظرف برای انتقال اطلاعاته. نام کسب‌وکار، شماره موبایل و رمز داخلش قرار می‌گیرن و کتابخانه Serialization اون رو به JSON تبدیل می‌کنه. اگر نام فیلدهای API با نام متغیرهای Kotlin یکسان نباشه، باید ارتباط بین اون‌ها رو مشخص کنیم. مثلاً سرور از business_name استفاده می‌کنه، اما در Kotlin طبق استاندارد از businessName استفاده می‌کنیم:

@SerialName("business_name")
val businessName: String

@SerialName("business_name")
val businessName: String

@SerialName میگه هنگام تبدیل آبجکت Kotlin به JSON، این متغیر با نام business_name ارسال بشه. بنابراین داخل برنامه همچنان کد خوانایی مثل businessName داریم، اما قرارداد سرور هم رعایت میشه.

تعریف درخواست در Retrofit

حالا باید به Retrofit بگیم برای ثبت‌نام، چه آدرسی رو صدا بزنه و چه اطلاعاتی رو بفرسته:

@POST("auth/register")
suspend fun register(
    @Body request: RegisterRequest
): RegisterResponse

@POST("auth/register")
suspend fun register(
    @Body request: RegisterRequest
): RegisterResponse

@POST مشخص می‌کنه نوع درخواست HTTP از نوع POST هست. ثبت‌نام باعث ایجاد یک کاربر یا کسب‌وکار جدید در سرور میشه، به همین دلیل معمولاً از POST استفاده می‌کنیم. عبارت “auth/register” مسیر Endpoint رو مشخص می‌کنه. Retrofit این مسیر رو به Base URL اضافه می‌کنه. مثلاً اگر Base URL این باشه:

https://api.gheymatban.com/

آدرس کامل درخواست به این صورت درمیاد:

https://api.gheymatban.com/auth/register

@Body یعنی آبجکت RegisterRequest باید داخل بدنه درخواست قرار بگیره. Serialization هم اون رو به JSON تبدیل می‌کنه. کلمه suspend به این معنیه که این تابع یک عملیات زمان‌بر انجام میده و باید داخل Coroutine اجرا بشه. درخواست اینترنت ممکنه یک یا چند ثانیه طول بکشه، بنابراین نباید Thread اصلی رابط کاربری رو متوقف کنه.

خروجی تابع هم RegisterResponse هست؛ یعنی Retrofit انتظار داره پاسخ موفق سرور رو به این مدل تبدیل کنه.

پاسخ سرور شامل چیه؟

بعد از ثبت‌نام موفق، سرور ممکنه اطلاعات کسب‌وکار و Tokenهای ورود رو برگردونه:

data class RegisterResponse(
    val accessToken: String,
    val refreshToken: String,
    val business: BusinessDto
)

data class RegisterResponse(
    val accessToken: String,
    val refreshToken: String,
    val business: BusinessDto
)

این فقط یک نمونه از قرارداد احتمالی API هست. ساختار دقیق پاسخ باید با Backend قیمت‌بان هماهنگ باشه.

accessToken برای درخواست‌های احراز هویت‌شده استفاده میشه. refreshToken هم زمانی کاربرد داره که Access Token منقضی شده و برنامه می‌خواد بدون درخواست دوباره رمز عبور، Token جدید بگیره. اطلاعات business هم می‌تونه شامل شناسه، نام کسب‌وکار، شماره موبایل و سایر مشخصات حساب ساخته‌شده باشه. این مدل در واقع ترجمه پاسخ JSON سرور به یک آبجکت قابل استفاده داخل Kotlin هست.

Repository؛ جایی که ثبت‌نام واقعاً انجام میشه

ViewModel نباید مستقیماً api.register رو اجرا کنه. این کار رو به Repository می‌سپاریم:

val response = api.register(
    RegisterRequest(
        businessName = businessName,
        phone = phone,
        password = password
    )
)

val response = api.register(
    RegisterRequest(
        businessName = businessName,
        phone = phone,
        password = password
    )
)

در اینجا Repository ابتدا اطلاعات جداگانه رو داخل RegisterRequest قرار میده. بعد این مدل رو برای Retrofit می‌فرسته. Retrofit درخواست HTTP رو می‌سازه، JSON رو ارسال می‌کنه و پاسخ سرور رو به RegisterResponse تبدیل می‌کنه.

در صورت موفقیت، Tokenها باید ذخیره بشن:

tokenStorage.saveTokens(
    accessToken = response.accessToken,
    refreshToken = response.refreshToken
)

tokenStorage.saveTokens(
    accessToken = response.accessToken,
    refreshToken = response.refreshToken
)

این بخش باعث میشه کاربر بعد از ثبت‌نام، مستقیماً وارد حسابش بشه. اگر Tokenها ذخیره نشن، ثبت‌نام روی سرور انجام شده، اما برنامه در اجرای بعدی نمی‌دونه کاربر وارد حساب شده. اینجا Repository دو کار مرتبط با داده رو هماهنگ می‌کنه: اول اطلاعات رو از API دریافت می‌کنه و بعد نتیجه لازم رو در حافظه امن گوشی ذخیره می‌کنه. ViewModel لازم نیست بدونه Token دقیقاً در کجا یا با چه روشی ذخیره شده.

در پایان، Repository می‌تونه اطلاعات کسب‌وکار ساخته‌شده رو برگردونه:

return response.business

return response.business

از اینجا به بعد ViewModel می‌فهمه ثبت‌نام موفق بوده، اما همچنان وارد جزئیات شبکه و Token نشده.

ViewModel چطور وضعیت ثبت‌نام رو مدیریت می‌کنه؟

ثبت‌نام فقط دو حالت موفق و ناموفق نداره. از لحظه‌ای که کاربر روی دکمه می‌زنه تا وقتی جواب سرور برمی‌گرده، چند وضعیت مختلف داریم:

sealed interface RegisterUiState {
    data object Idle : RegisterUiState
    data object Loading : RegisterUiState
    data object Success : RegisterUiState
    data class Error(val message: String) : RegisterUiState
}

sealed interface RegisterUiState {
    data object Idle : RegisterUiState
    data object Loading : RegisterUiState
    data object Success : RegisterUiState
    data class Error(val message: String) : RegisterUiState
}

Idle یعنی هنوز فرایند ثبت‌نام شروع نشده. Loading یعنی درخواست ارسال شده و منتظر پاسخ هستیم. Success یعنی حساب با موفقیت ساخته شده و Error یعنی مشکلی اتفاق افتاده. از sealed interface استفاده می‌کنیم چون وضعیت صفحه باید فقط یکی از همین حالت‌های تعریف‌شده باشه. این ساختار اجازه نمیده صفحه وارد وضعیت مبهمی بشه که هم‌زمان هم Loading باشه، هم Success و هم Error.

ViewModel یک StateFlow از این وضعیت نگه می‌داره:

private val _uiState =
    MutableStateFlow<RegisterUiState>(RegisterUiState.Idle)

val uiState = _uiState.asStateFlow()

private val _uiState =
    MutableStateFlow<RegisterUiState>(RegisterUiState.Idle)

val uiState = _uiState.asStateFlow()

نسخه _uiState خصوصی و قابل تغییره، بنابراین فقط خود ViewModel می‌تونه وضعیت رو عوض کنه. نسخه uiState عمومی اما فقط خواندنیه. صفحه می‌تونه تغییراتش رو ببینه، اما نمی‌تونه مستقیماً مقدارش رو تغییر بده. این موضوع جلوی تغییرات کنترل‌نشده State رو می‌گیره. صفحه فقط رویداد می‌فرسته و ViewModel تنها مرجع تغییر وضعیت باقی می‌مونه.

اجرای عملیات ثبت‌نام

بعد از اعتبارسنجی، ViewModel عملیات ثبت‌نام رو داخل Coroutine اجرا می‌کنه:

_uiState.value = RegisterUiState.Loading

viewModelScope.launch {
    repository.register(
        businessName = businessName,
        phone = phone,
        password = password
    )
}

_uiState.value = RegisterUiState.Loading

viewModelScope.launch {
    repository.register(
        businessName = businessName,
        phone = phone,
        password = password
    )
}

قبل از شروع درخواست، State روی Loading قرار می‌گیره. Compose این تغییر رو می‌بینه و می‌تونه دکمه رو غیرفعال کنه یا یک نشانگر بارگذاری نمایش بده.

از viewModelScope.launch استفاده می‌کنیم چون تابع Repository یک عملیات suspend داره. viewModelScope هم به عمر ViewModel متصله. اگر کاربر صفحه رو ترک کنه و ViewModel از بین بره، Coroutineهای مرتبط با اون هم لغو میشن.

بعد از دریافت پاسخ موفق، وضعیت تغییر می‌کنه:

_uiState.value = RegisterUiState.Success

_uiState.value = RegisterUiState.Success

اما درخواست اینترنت همیشه موفق نیست. ممکنه اینترنت قطع باشه، سرور جواب نده، شماره موبایل قبلاً ثبت شده باشه یا اطلاعات ارسالی معتبر نباشن. بنابراین باید خطا رو هم مدیریت کنیم:

try {
    repository.register(businessName, phone, password)
    _uiState.value = RegisterUiState.Success
} catch (error: Exception) {
    _uiState.value = RegisterUiState.Error(
        message = error.toUserMessage()
    )
}

try {
    repository.register(businessName, phone, password)
    _uiState.value = RegisterUiState.Success
} catch (error: Exception) {
    _uiState.value = RegisterUiState.Error(
        message = error.toUserMessage()
    )
}

try بخشی از کده که ممکنه خطا تولید کنه. اگر ثبت‌نام موفق باشه، State به Success تغییر می‌کنه. اگر Exception رخ بده، اجرای کد وارد catch میشه و وضعیت خطا به صفحه فرستاده میشه. تابع toUserMessage یک تابع فرضیه که خطای فنی رو به پیام قابل فهم برای کاربر تبدیل می‌کنه. مثلاً به جای نمایش عبارت پیچیده‌ای مثل SocketTimeoutException، پیام پاسخ سرور بیش از حد طول کشید نمایش داده میشه.

جلوگیری از چندبار ثبت درخواست

فرض کن کاربر روی دکمه ثبت‌نام چند بار پشت سر هم ضربه بزنه. اگر دکمه همچنان فعال بمونه، ممکنه چند درخواست یکسان به سرور فرستاده بشه. برای جلوگیری از این اتفاق، هنگام Loading دکمه رو غیرفعال می‌کنیم:

Button( enabled = uiState !is RegisterUiState.Loading, onClick = { viewModel.register(businessName, phone, password) } )

خصوصیت enabled مشخص می‌کنه دکمه قابل کلیک باشه یا نه. وقتی State از نوع Loading باشه، نتیجه شرط false میشه و دکمه موقتاً غیرفعال میشه. این یک خط ساده است، اما جلوی خطاهای واقعی زیادی رو می‌گیره؛ از ساخت چند حساب تکراری گرفته تا ارسال چند درخواست هم‌زمان و گیج شدن کاربر. داخل دکمه هم میشه براساس وضعیت، متن یا Loading نمایش داد:

if (uiState is RegisterUiState.Loading) {
    CircularProgressIndicator()
} else {
    Text("ثبت‌نام")
}

if (uiState is RegisterUiState.Loading) {
    CircularProgressIndicator()
} else {
    Text("ثبت‌نام")
}

وقتی درخواست در حال اجراست، نشانگر بارگذاری نمایش داده میشه. در حالت عادی هم متن ثبت‌نام دیده میشه. این بازخورد به کاربر میگه که لمس دکمه ثبت شده و برنامه در حال انجام کاره.

صفحه چطور موفقیت رو تشخیص میده؟

صفحه باید StateFlow رو مشاهده کنه:

val uiState by viewModel.uiState.collectAsStateWithLifecycle()

val uiState by viewModel.uiState.collectAsStateWithLifecycle()

این خط StateFlow داخل ViewModel رو به State قابل استفاده در Compose تبدیل می‌کنه. هر بار که ViewModel مقدار uiState رو تغییر بده، Compose متوجه میشه و بخش‌های وابسته رو دوباره اجرا می‌کنه.

عبارت WithLifecycle باعث میشه جمع‌آوری State با چرخه حیات صفحه هماهنگ باشه. یعنی وقتی صفحه در وضعیت فعال نیست، بی‌دلیل تغییرات رو جمع‌آوری نمی‌کنه. این رفتار هم مصرف منابع رو کمتر می‌کنه و هم از برخی خطاهای مربوط به Lifecycle جلوگیری می‌کنه.

حالا میشه در صورت موفقیت، کاربر رو وارد صفحه اصلی کرد:

LaunchedEffect(uiState) { if (uiState is RegisterUiState.Success) { navController.navigate(“home”) { popUpTo(“register”) { inclusive = true } } } }

LaunchedEffect برای اجرای یک اثر جانبی در واکنش به تغییر State استفاده میشه. Navigation تغییر مستقیم ظاهر یک Composable نیست؛ یک عمل بیرونی محسوب میشه، به همین دلیل داخل LaunchedEffect قرار می‌گیره. وقتی State به Success تغییر می‌کنه، کاربر وارد صفحه Home میشه. بخش popUpTo(“register”) صفحه ثبت‌نام رو از Back Stack حذف می‌کنه. inclusive = true هم یعنی خود صفحه ثبت‌نام نیز حذف بشه. بنابراین اگر کاربر داخل Home دکمه Back رو بزنه، دوباره به فرم ثبت‌نام برنمی‌گرده.

این نکته کوچکیه، اما رفتار Navigation رو حرفه‌ای‌تر می‌کنه. بعد از ساخت حساب، برگشتن به فرم ثبت‌نام معمولاً معنایی نداره.

خطا چطور نمایش داده میشه؟

اگر State از نوع Error باشه، صفحه می‌تونه پیام رو نمایش بده:

if (uiState is RegisterUiState.Error) {
    Text(
        text = (uiState as RegisterUiState.Error).message
    )
}

if (uiState is RegisterUiState.Error) {
    Text(
        text = (uiState as RegisterUiState.Error).message
    )
}

اما این روش برای خواندن State کمی تکراریه. ساختار when معمولاً خواناتر میشه:

when (val state = uiState) {
    RegisterUiState.Idle -> Unit
    RegisterUiState.Loading -> LoadingView()
    RegisterUiState.Success -> Unit
    is RegisterUiState.Error -> ErrorText(state.message)
}

when (val state = uiState) {
    RegisterUiState.Idle -> Unit
    RegisterUiState.Loading -> LoadingView()
    RegisterUiState.Success -> Unit
    is RegisterUiState.Error -> ErrorText(state.message)
}

when تمام حالت‌های RegisterUiState رو جدا می‌کنه. چون State به شکل sealed تعریف شده، Kotlin می‌دونه چه حالت‌هایی ممکنه وجود داشته باشن. اگر بعداً حالت جدیدی اضافه کنیم، کامپایلر یادآوری می‌کنه که این قسمت هم باید به‌روزرسانی بشه.

این یکی از مزیت‌های مهم طراحی State به شکل مشخص و محدود است. به جای چند متغیر پراکنده مثل isLoading، isSuccess و errorMessage، یک وضعیت واحد داریم که دقیقاً مشخص می‌کنه صفحه در چه حالتی قرار گرفته.

خطای شماره موبایل قبلاً ثبت شده

همه خطاها فنی نیستن. گاهی سرور سالمه، اینترنت هم وجود داره، اما درخواست از نظر منطق برنامه قابل قبول نیست. مثلاً شماره موبایل قبلاً برای یک کسب‌وکار ثبت شده. سرور ممکنه در این حالت کد HTTP مثل 409 Conflict برگردونه. Repository یا لایه مدیریت خطا می‌تونه اون رو به یک خطای قابل فهم تبدیل کنه:

if (response.code() == 409) {
    throw DuplicatePhoneException()
}

if (response.code() == 409) {
    throw DuplicatePhoneException()
}

کد 409 یعنی درخواست با وضعیت فعلی داده‌های سرور تعارض داره. در این مثال، تعارض اینه که شماره موبایل از قبل وجود داره. بعد این خطا به یک پیام مناسب تبدیل میشه:

is DuplicatePhoneException ->
    "این شماره موبایل قبلاً ثبت شده"

is DuplicatePhoneException ->
    "این شماره موبایل قبلاً ثبت شده"

نباید متن خام پاسخ سرور یا نام Exception رو مستقیماً به کاربر نمایش بدیم. پیام خطا باید بگه چه اتفاقی افتاده و کاربر برای حلش چه کاری می‌تونه انجام بده. مثلاً پیام خطای 409 هیچ کمکی به کاربر نمی‌کنه، اما این شماره موبایل قبلاً ثبت شده؛ وارد حساب شو هم مشکل رو توضیح میده و هم مسیر بعدی رو مشخص می‌کنه.

آیا ثبت‌نام در حالت آفلاین ممکنه؟

در درس قبلی درباره Offline First صحبت کردیم. اما همه عملیات‌ها رو نمی‌شه به صورت کامل آفلاین انجام داد. ساخت حساب جدید یکی از همین موارده، چون سرور باید بررسی کنه شماره موبایل تکراری نباشه، شناسه کسب‌وکار ایجاد کنه و Token معتبر صادر کنه.

بنابراین اگر اینترنت قطع باشه، برنامه نمی‌تونه وانمود کنه که ثبت‌نام کامل انجام شده. در این وضعیت بهتره اطلاعات داخل فرم حفظ بشن و پیام مناسبی نمایش داده بشه:

“No internet connection”

البته پیام واقعی برای کاربر فارسی خواهد بود:

اینترنت وصل نیست. اطلاعات فرم حفظ شده؛ بعد از اتصال دوباره تلاش کن.

در اینجا Offline First به معنی ثبت‌نام جعلی نیست. به این معنیه که برنامه در نبود اینترنت رفتار مناسبی داشته باشه، اطلاعات واردشده رو از بین نبره و کاربر رو مجبور نکنه همه چیز رو دوباره تایپ کنه.

بعد از ثبت‌نام چه چیزهایی باید ذخیره بشن؟

مهم‌ترین اطلاعاتی که باید ذخیره بشن، Tokenهای Session هستن. اما ممکنه اطلاعات اصلی کسب‌وکار هم داخل Room ذخیره بشن:

businessDao.insert(
    response.business.toEntity()
)

businessDao.insert(
    response.business.toEntity()
)

response.business مدلیه که از API دریافت شده. اما مدل API لزوماً نباید مستقیماً داخل Room ذخیره بشه. تابع toEntity مدل شبکه رو به مدل دیتابیس تبدیل می‌کنه. این جداسازی باعث میشه ساختار JSON سرور و ساختار جدول Room به هم وابسته نشن. اگر API تغییر کرد، مجبور نیستیم کل دیتابیس محلی رو هم تغییر بدیم. بعد از ذخیره Token و اطلاعات کسب‌وکار، برنامه می‌تونه صفحه Home رو از اطلاعات محلی تغذیه کنه. اینجا مفاهیم Repository، Room، Cache و Offline First دوباره به هم وصل میشن.

ثبت‌نام یک دکمه نیست؛ یک فراینده

در ظاهر، کاربر فقط چند فیلد می‌بینه و یک دکمه رو لمس می‌کنه. اما پشت همین دکمه، چند اتفاق هماهنگ رخ میده. ورودی‌ها اعتبارسنجی میشن، State به Loading تغییر می‌کنه، مدل درخواست ساخته میشه، Retrofit JSON رو به سرور می‌فرسته، سرور کسب‌وکار رو ایجاد می‌کنه، Tokenها برمی‌گردن، Repository اون‌ها رو ذخیره می‌کنه و ViewModel وضعیت موفقیت رو به صفحه اعلام می‌کنه. در نهایت Navigation کاربر رو وارد Home می‌کنه.

نکته مهم این درس خود فرم ثبت‌نام نبود. چیزی که باید یاد بگیری، تقسیم مسئولیت‌ها در یک فرایند واقعی بود.

صفحه اطلاعات رو می‌گیره و وضعیت رو نمایش میده. ViewModel فرایند و State رو مدیریت می‌کنه. Repository کارهای مرتبط با داده رو هماهنگ می‌کنه. Retrofit با سرور حرف می‌زنه. TokenStorage اطلاعات ورود رو نگه می‌داره و Room در صورت نیاز اطلاعات کسب‌وکار رو ذخیره می‌کنه.

اگر تمام این کارها رو داخل onClick دکمه می‌نوشتیم، شاید در ابتدا سریع‌تر پیش می‌رفتیم؛ اما خیلی زود کدی شلوغ، شکننده و غیرقابل آزمایش داشتیم. معماری درست باعث نمیشه کد کمتری بنویسیم؛ باعث میشه هر کد رو در جای درست خودش بنویسیم.

در پایان، مسیر ثبت‌نام قیمت‌بان رو میشه در یک جمله خلاصه کرد: صفحه درخواست ثبت‌نام رو اعلام می‌کنه، ViewModel فرایند رو کنترل می‌کنه، Repository ثبت‌نام رو انجام میده و State نتیجه رو دوباره به صفحه برمی‌گردونه.

درس بیست‌ودوم

وقتی کاربر دوباره وارد برنامه میشه، اپلیکیشن چطور هویت واقعی اون رو تشخیص میده؟

ورود به حساب کاربری

ثبت‌نام فقط یک‌بار انجام میشه، اما ورود ممکنه بارها تکرار بشه. کاربر برنامه رو روی گوشی جدید نصب می‌کنه، از حساب خارج میشه، Token قبلی منقضی میشه یا اطلاعات برنامه پاک میشه. در همه این حالت‌ها، برنامه باید دوباره از کاربر اطلاعات ورود رو بگیره و از سرور بخواد هویت اون رو تأیید کنه.

در نگاه اول، ورود خیلی شبیه ثبت‌نامه. کاربر شماره موبایل و رمز عبور رو وارد می‌کنه، برنامه اطلاعات رو به سرور می‌فرسته و در صورت درست بودن اطلاعات، Token دریافت می‌کنه. اما تفاوت مهمی وجود داره. در ثبت‌نام، سرور یک حساب جدید می‌سازه؛ در ورود، سرور باید یک حساب موجود رو پیدا کنه، رمز واردشده رو بررسی کنه و فقط در صورت تطابق، اجازه ورود بده.

مسیر کلی ورود در قیمت‌بان به این شکله:

LoginScreen
↓
LoginViewModel
↓
AuthRepository
↓
AuthApi
↓
Server
↓
Access Token + Refresh Token
↓
TokenStorage
↓
Home

ظاهر مسیر شبیه ثبت‌نامه، اما معنی عملیات فرق می‌کنه. این بار سرور چیزی نمی‌سازه؛ فقط بررسی می‌کنه آیا این کاربر واقعاً همون فردیه که ادعا می‌کنه یا نه.

صفحه ورود چه مسئولیتی داره؟

صفحه ورود فقط باید اطلاعات کاربر رو بگیره، رویداد کلیک رو به ViewModel بفرسته و وضعیت عملیات رو نمایش بده. این صفحه نباید درباره رمزنگاری رمز، جست‌وجوی کاربر در دیتابیس یا ساخت Token چیزی بدونه. برای نگهداری اطلاعات فرم، دوباره می‌تونیم از rememberSaveable استفاده کنیم:

var phone by rememberSaveable { mutableStateOf("") }
var password by rememberSaveable { mutableStateOf("") }

var phone by rememberSaveable { mutableStateOf("") }
var password by rememberSaveable { mutableStateOf("") }

استفاده از rememberSaveable باعث میشه اگر Activity دوباره ساخته شد، شماره موبایل و رمز واردشده فوراً ناپدید نشن. البته درباره رمز عبور باید کمی محتاط باشیم. حفظ موقت مقدار رمز در State صفحه معمولاً برای فرم ورود عادیه، اما نباید اون رو داخل دیتابیس، Log یا حافظه دائمی ذخیره کنیم. صفحه ورود فقط تا زمانی که کاربر در حال تکمیل فرمه، رمز رو نگه می‌داره. بعد از ورود موفق، دیگر نیازی به حفظ خود رمز وجود نداره؛ چیزی که باید ذخیره بشه Tokenهست، نه Password.

ارسال اطلاعات به ViewModel

وقتی کاربر روی دکمه ورود می‌زنه، اطلاعات فرم به ViewModel تحویل داده میشه:

viewModel.login(
    phone = phone.trim(),
    password = password
)

viewModel.login(
    phone = phone.trim(),
    password = password
)

برای شماره موبایل از trim استفاده کردیم تا فاصله‌های ابتدا و انتهای اون حذف بشن. اما رمز عبور رو بدون تغییر می‌فرستیم، چون برنامه نباید چیزی رو که کاربر به عنوان رمز وارد کرده، خودسرانه تغییر بده. این کد نمیگه به سرور وصل شو. فقط به ViewModel میگه کاربر درخواست ورود داده و این هم اطلاعاتیه که وارد کرده.

همین جداسازی باعث میشه اگر بعداً روش ورود تغییر کرد، مثلاً ورود با ایمیل، کد یک‌بارمصرف یا اثر انگشت اضافه شد، صفحه مجبور نباشه تمام جزئیات فنی رو مدیریت کنه.

اعتبارسنجی اولیه ورود

قبل از ارسال درخواست، باید خطاهای ساده رو داخل برنامه بررسی کنیم. مثلاً شماره موبایل خالی نباشه و رمز عبور هم وارد شده باشه:

if (phone.isBlank() || password.isBlank()) {
    showError("شماره موبایل و رمز عبور رو وارد کن")
    return
}

if (phone.isBlank() || password.isBlank()) {
    showError("شماره موبایل و رمز عبور رو وارد کن")
    return
}

این بررسی فقط جلوی درخواست‌های بیهوده رو می‌گیره. وقتی هیچ شماره یا رمزی وارد نشده، دلیلی نداره یک درخواست شبکه ارسال بشه. اما برخلاف ثبت‌نام، در ورود بهتره بیش از حد درباره ساختار رمز سخت‌گیری نکنیم. فرض کن قوانین فعلی میگن رمز باید حداقل هشت کاراکتر باشه، اما بعضی کاربران قدیمی قبلاً با رمز شش‌کاراکتری ثبت‌نام کردن. اگر اپلیکیشن قبل از ارسال درخواست اون‌ها رو رد کنه، این کاربران حتی فرصت بررسی اطلاعات توسط سرور رو پیدا نمی‌کنن. پس در ورود، اعتبارسنجی سمت اپ معمولاً ساده‌تره. بررسی اصلی اینکه آیا شماره و رمز واقعاً درست هستن، باید در سرور انجام بشه.

مدل درخواست ورود

سرور معمولاً برای ورود، یک JSON ساده دریافت می‌کنه:

{
  "phone": "09121234567",
  "password": "12345678"
}

{
  "phone": "09121234567",
  "password": "12345678"
}

مدل Kotlin متناظر با این درخواست می‌تونه به این شکل باشه:

data class LoginRequest(
    val phone: String,
    val password: String
)

data class LoginRequest(
    val phone: String,
    val password: String
)

این مدل قرارداد درخواست ورود بین اپلیکیشن و سروره. Retrofit و Serialization این آبجکت رو به JSON تبدیل می‌کنن و در بدنه درخواست قرار میدن. شاید بگی چرا نمی‌تونیم شماره و رمز رو جداگانه به Retrofit بدیم؟ از نظر فنی گاهی میشه، اما داشتن یک مدل مشخص باعث میشه ساختار درخواست روشن‌تر و قابل نگهداری‌تر باشه. هر کسی کد رو ببینه، سریع می‌فهمه Endpoint ورود دقیقاً چه اطلاعاتی دریافت می‌کنه.

تعریف Endpoint ورود

در لایه Retrofit، فقط بخش متمایز ورود رو تعریف می‌کنیم:

@POST("auth/login")
suspend fun login(
    @Body request: LoginRequest
): LoginResponse

@POST("auth/login")
suspend fun login(
    @Body request: LoginRequest
): LoginResponse

@POST یعنی اطلاعات ورود داخل بدنه یک درخواست POST فرستاده میشن. مسیر auth/login هم Endpoint ورود رو مشخص می‌کنه. از GET برای ارسال رمز عبور استفاده نمی‌کنیم، چون پارامترهای GET معمولاً داخل URL قرار می‌گیرن و ممکنه در تاریخچه، Logها یا ابزارهای مانیتورینگ ثبت بشن. ورود باید از یک اتصال امن HTTPS و بدنه درخواست استفاده کنه. کلمه suspend هم به این معنیه که عملیات ورود باید داخل Coroutine اجرا بشه. برنامه نباید هنگام انتظار برای پاسخ سرور، رابط کاربری رو متوقف کنه.

پاسخ ورود چه اطلاعاتی داره؟

پاسخ موفق ورود معمولاً شبیه پاسخ ثبت‌نامه:

data class LoginResponse(
    val accessToken: String,
    val refreshToken: String,
    val business: BusinessDto
)

data class LoginResponse(
    val accessToken: String,
    val refreshToken: String,
    val business: BusinessDto
)

accessToken برای درخواست‌های روزمره استفاده میشه. مثلاً وقتی کاربر می‌خواد لیست کالاها یا قیمت‌های کسب‌وکار خودش رو دریافت کنه، این Token همراه درخواست فرستاده میشه. refreshToken برای گرفتن Access Token جدید استفاده میشه. چون Access Token معمولاً عمر کوتاه‌تری داره، برنامه نباید بعد از هر انقضا کاربر رو مجبور کنه دوباره شماره و رمز رو وارد کنه. اطلاعات business هم کمک می‌کنه برنامه بعد از ورود بدونه این Session متعلق به کدوم کسب‌وکاره.

ساختار دقیق این پاسخ به Backend قیمت‌بان بستگی داره، اما منطق کلی همین می‌مونه: سرور بعد از تأیید هویت، مدرکی موقت برای ادامه ارتباط صادر می‌کنه.

Repository عملیات ورود رو انجام میده

ViewModel اطلاعات رو به Repository می‌فرسته و Repository درخواست واقعی رو می‌سازه:

val response = api.login(
    LoginRequest(
        phone = phone,
        password = password
    )
)

val response = api.login(
    LoginRequest(
        phone = phone,
        password = password
    )
)

در این بخش، اطلاعات جداگانه داخل LoginRequest قرار می‌گیرن و به Retrofit تحویل داده میشن. Retrofit درخواست رو می‌فرسته و پاسخ JSON رو به LoginResponse تبدیل می‌کنه.

بعد از ورود موفق، Tokenها ذخیره میشن:

tokenStorage.saveTokens(
    accessToken = response.accessToken,
    refreshToken = response.refreshToken
)

tokenStorage.saveTokens(
    accessToken = response.accessToken,
    refreshToken = response.refreshToken
)

با همین دو Token، Session کاربر ساخته میشه. از این لحظه به بعد، برنامه لازم نیست برای هر درخواست دوباره شماره موبایل و رمز رو بفرسته. این نکته خیلی مهمه: رمز عبور ابزار اثبات اولیه هویته، اما Token مدرک ادامه Session هست. یعنی کاربر یک بار با رمز خودش رو معرفی می‌کنه و بعد سرور Tokenی صادر می‌کنه که در درخواست‌های بعدی نقش کارت ورود رو داره.

آیا اطلاعات کسب‌وکار هم ذخیره میشه؟

بعد از ورود، Repository می‌تونه اطلاعات کسب‌وکار رو داخل Room ذخیره یا به‌روزرسانی کنه:

businessDao.insert(
    response.business.toEntity()
)

businessDao.insert(
    response.business.toEntity()
)

این اطلاعات ممکنه قبلاً داخل دیتابیس وجود داشته باشن. مثلاً کاربر قبلاً وارد شده، از حساب خارج شده و دوباره وارد همون حساب شده. در این حالت بهتره عملیات ذخیره طوری تعریف شده باشه که نسخه قبلی رو به‌روزرسانی کنه، نه اینکه یک رکورد تکراری بسازه.

هدف اینه که بعد از ورود، صفحه Home مجبور نباشه برای نمایش نام کسب‌وکار دوباره منتظر اینترنت بمونه. اطلاعات اولیه از Room نمایش داده میشن و در صورت نیاز بعداً با سرور همگام میشن.

State صفحه ورود

صفحه ورود هم مثل ثبت‌نام چند وضعیت مختلف داره:

sealed interface LoginUiState {
    data object Idle : LoginUiState
    data object Loading : LoginUiState
    data object Success : LoginUiState
    data class Error(val message: String) : LoginUiState
}

sealed interface LoginUiState {
    data object Idle : LoginUiState
    data object Loading : LoginUiState
    data object Success : LoginUiState
    data class Error(val message: String) : LoginUiState
}

Idle یعنی هنوز درخواستی ارسال نشده. Loading یعنی برنامه منتظر پاسخ سروره. Success یعنی هویت کاربر تأیید شده و Tokenها ذخیره شدن. Error هم یعنی ورود کامل نشده. ممکنه در آینده حالت‌های دیگری هم اضافه بشن؛ مثلاً حساب غیرفعال، نیاز به تأیید شماره موبایل یا الزام تغییر رمز. مزیت sealed interface اینه که این وضعیت‌ها به شکل روشن و محدود تعریف میشن.

ViewModel هم StateFlow مربوط به اون رو نگه می‌داره:

private val _uiState = MutableStateFlow<LoginUiState>(LoginUiState.Idle) val uiState = _uiState.asStateFlow()

صفحه فقط uiState رو می‌خونه. تنها ViewModel اجازه داره مقدار _uiState رو تغییر بده. به این ترتیب، وضعیت ورود از یک نقطه مرکزی کنترل میشه.

اجرای ورود داخل ViewModel

ViewModel قبل از شروع درخواست، وضعیت رو روی Loading قرار میده:

_uiState.value = LoginUiState.Loading

بعد عملیات داخل viewModelScope اجرا میشه:

viewModelScope.launch { repository.login(phone, password) }

این کد باعث میشه عملیات زمان‌بر ورود خارج از روند عادی رابط کاربری اجرا بشه. ViewModel هم مسئول عمر Coroutine باقی می‌مونه.

نسخه کامل‌تر بخش متمایز عملیات به این شکله:

viewModelScope.launch { try { repository.login(phone, password) _uiState.value = LoginUiState.Success } catch (error: Exception) { _uiState.value = LoginUiState.Error( error.toUserMessage() ) } }

اگر Repository بدون خطا کارش رو تمام کنه، یعنی سرور اطلاعات رو پذیرفته و Tokenها ذخیره شدن. پس State به Success تغییر می‌کنه. اگر خطایی رخ بده، اون خطا به پیام قابل فهم تبدیل میشه و صفحه می‌تونه اون رو نمایش بده.

تفاوت خطای فنی و خطای اطلاعات ورود

در ورود، یکی از مهم‌ترین موضوعات اینه که همه خطاها یکسان نیستن. ممکنه اینترنت قطع باشه، سرور در دسترس نباشه یا شماره و رمز اشتباه باشن. این سه وضعیت از دید کاربر معنای متفاوتی دارن:

اینترنت قطع است.
سرور فعلاً پاسخ نمی‌دهد.
شماره موبایل یا رمز عبور اشتباه است.

اگر همه این موارد رو با پیام ورود ناموفق بود نمایش بدیم، کاربر نمی‌فهمه باید چه کاری انجام بده. آیا رمز رو عوض کنه؟ اینترنت رو بررسی کنه؟ یا چند دقیقه صبر کنه؟

بنابراین خطاها باید در لایه مناسب از هم تفکیک بشن. مثلاً اگر سرور کد 401 Unauthorized برگردونه، می‌تونیم اون رو به خطای اطلاعات ورود تبدیل کنیم:

if (response.code() == 401) { throw InvalidCredentialsException() }

کد 401 یعنی سرور هویت درخواست‌کننده رو نپذیرفته. در صفحه ورود، معمولاً این یعنی شماره موبایل یا رمز عبور درست نیست.

پیام کاربرپسند اون می‌تونه این باشه:

is InvalidCredentialsException -> “شماره موبایل یا رمز عبور اشتباهه”

دقت کن که بهتره مشخص نکنیم دقیقاً کدوم بخش اشتباه بوده. مثلاً نگیم این شماره موبایل در سیستم وجود نداره، چون این پیام می‌تونه به افراد مهاجم کمک کنه شماره‌های ثبت‌شده رو شناسایی کنن. پیام عمومی شماره موبایل یا رمز عبور اشتباهه از نظر امنیتی مناسب‌تره.

چرا نباید رمز عبور رو Log کنیم؟

هنگام توسعه ممکنه وسوسه بشیم اطلاعات ارسالی رو با Logcat بررسی کنیم:

Log.d(“LOGIN”, “phone=$phone password=$password”)

این کار اشتباهه. Logها ممکنه روی دستگاه، ابزارهای خطایابی یا سرویس‌های گزارش خطا باقی بمونن. رمز عبور نباید در هیچ Log، دیتابیس محلی یا فایل معمولی ذخیره بشه. حتی اگر برای آزمایش از حساب فرضی استفاده می‌کنیم، بهتره از ابتدا عادت کنیم اطلاعات حساس رو وارد Log نکنیم.

می‌تونیم صرفاً شروع عملیات رو ثبت کنیم:

Log.d(“LOGIN”, “Login request started”)

این Log برای فهمیدن اینکه درخواست اجرا شده کافیه و هیچ اطلاعات محرمانه‌ای رو فاش نمی‌کنه.

دکمه ورود هنگام Loading

مثل ثبت‌نام، هنگام ارسال درخواست باید دکمه ورود غیرفعال بشه:

enabled = uiState !is LoginUiState.Loading

enabled = uiState !is LoginUiState.Loading

با این شرط، تا وقتی پاسخ قبلی برنگشته، کاربر نمی‌تونه دوباره روی دکمه ضربه بزنه. هم‌زمان میشه داخل دکمه Loading نمایش داد:

if (uiState is LoginUiState.Loading) {
    CircularProgressIndicator()
} else {
    Text("ورود")
}

if (uiState is LoginUiState.Loading) {
    CircularProgressIndicator()
} else {
    Text("ورود")
}

این بازخورد ساده باعث میشه کاربر بفهمه درخواست در حال انجامه. بدون اون، ممکنه تصور کنه دکمه کار نکرده و چند بار دوباره لمسش کنه.

انتقال کاربر به صفحه Home

صفحه StateFlow رو مشاهده می‌کنه:

val uiState by viewModel.uiState.collectAsStateWithLifecycle()

val uiState by viewModel.uiState.collectAsStateWithLifecycle()

هر زمان ViewModel مقدار State رو تغییر بده، Compose وضعیت جدید رو دریافت می‌کنه. وقتی ورود موفق شد، Navigation انجام میشه:

LaunchedEffect(uiState) {
    if (uiState is LoginUiState.Success) {
        navController.navigate("home") {
            popUpTo("login") {
                inclusive = true
            }
        }
    }
}

LaunchedEffect(uiState) {
    if (uiState is LoginUiState.Success) {
        navController.navigate("home") {
            popUpTo("login") {
                inclusive = true
            }
        }
    }
}

بعد از ورود موفق، صفحه Login از Back Stack حذف میشه. بنابراین کاربر با زدن دکمه Back دوباره وارد فرم ورود نمیشه. در برنامه واقعی ممکنه لازم باشه علاوه بر Login، صفحه‌های Welcome یا Register هم از Back Stack حذف بشن. در این صورت، معمولاً یک مسیر والد مثل auth تعریف می‌کنیم و کل بخش احراز هویت رو از تاریخچه Navigation کنار می‌ذاریم. منطق اصلی اینه که بعد از ایجاد Session، مسیر قبلی احراز هویت دیگر نباید بخشی از روند عادی کاربر باشه.

آیا بعد از ورود باید رمز عبور پاک بشه؟

اگر ورود ناموفق باشه، معمولاً بهتره شماره موبایل حفظ بشه تا کاربر مجبور نباشه دوباره اون رو تایپ کنه. اما درباره رمز عبور دو انتخاب داریم. بعضی برنامه‌ها رمز رو حفظ می‌کنن تا کاربر فقط اشتباه کوچکش رو اصلاح کنه. بعضی برنامه‌ها بعد از خطای ورود، فیلد رمز رو پاک می‌کنن تا از باقی موندن اطلاعات حساس جلوگیری بشه. در صورت ورود موفق، قطعاً بهتره State فرم پاک بشه یا صفحه از Back Stack حذف بشه:

password = “”

این کد رمز رو از State محلی صفحه حذف می‌کنه. البته چون صفحه بعد از ورود موفق حذف میشه، معمولاً State اون هم همراه صفحه از بین میره. اما خالی کردن صریح رمز می‌تونه رفتار روشن‌تر و مطمئن‌تری ایجاد کنه.

گزینه مرا به خاطر بسپار چه معنی‌ای داره؟

در بسیاری از فرم‌های ورود، گزینه‌ای به نام مرا به خاطر بسپار وجود داره. اما در اپلیکیشن‌های موبایل، مفهوم اون با وب کمی فرق می‌کنه. ما نباید شماره و رمز عبور رو ذخیره کنیم و هر بار دوباره به سرور بفرستیم. چیزی که حفظ می‌کنیم Tokenهای Session هستن. اگر Tokenها هنوز معتبر باشن یا با Refresh Token قابل تمدید باشن، کاربر بدون دیدن صفحه ورود وارد برنامه میشه.

پس Auto Login یعنی:

وجود Token معتبر یا امکان گرفتن Access Token جدید با Refresh Token

نه اینکه رمز عبور کاربر رو داخل گوشی نگه داریم. در واقع ورود موفق فقط پایان صفحه Login نیست؛ شروع Sessionیه که در درس‌های قبلی درباره اون صحبت کردیم.

ورود خودکار در اجرای بعدی برنامه

بعد از اینکه Tokenها ذخیره شدن، اجرای بعدی برنامه نباید مستقیم صفحه Login رو باز کنه. صفحه آغازین یا Splash باید وضعیت Session رو بررسی کنه:

val hasSession = tokenStorage.hasRefreshToken()

val hasSession = tokenStorage.hasRefreshToken()

اگر Refresh Token وجود داشته باشه، برنامه می‌تونه تلاش کنه Session رو بازیابی کنه. اگر Token معتبر بود، کاربر به Home میره. اگر منقضی یا نامعتبر بود، Tokenها پاک میشن و صفحه Login نمایش داده میشه. صرفاً وجود یک Access Token به معنی معتبر بودن اون نیست. ممکنه Token منقضی شده باشه یا سرور اون رو باطل کرده باشه. بنابراین تصمیم نهایی باید با منطق Session و Refresh Token هماهنگ باشه. ورود کاربر با رمز، فقط یکی از راه‌های ایجاد Session هست. بعد از اون، مدیریت Session باید ادامه مسیر رو بر عهده بگیره.

ورود در حالت آفلاین

برخلاف نمایش داده‌های کش‌شده، ورود اولیه معمولاً به اینترنت نیاز داره. سرور باید رمز رو بررسی و Token معتبر صادر کنه. بنابراین وقتی هیچ Session قبلی وجود نداره، برنامه نمی‌تونه ورود واقعی رو کاملاً آفلاین انجام بده.

اما یک وضعیت متفاوت وجود داره. فرض کن کاربر قبلاً وارد شده و اطلاعات Session داخل گوشی وجود داره، اما الان اینترنت قطع شده. در یک معماری Offline First، ممکنه برنامه اجازه بده کاربر به بخش‌هایی از اطلاعات محلی دسترسی داشته باشه. این دیگه ورود با رمز در حالت آفلاین نیست؛ ادامه استفاده از یک Session قبلی و داده‌های محلیه. اگر هیچ Session قبلی وجود نداشته باشه، پیام مناسب اینه:

برای ورود به حساب، اتصال اینترنت لازمه.

اما اگر Session قبلی موجوده و فقط اینترنت قطع شده، برنامه می‌تونه آخرین اطلاعات ذخیره‌شده رو نمایش بده و همگام‌سازی رو به بعد موکول کنه.

امنیت واقعی رمز عبور در سمت سرور

اپلیکیشن رمز رو از طریق HTTPS برای سرور می‌فرسته، اما سرور هم نباید اون رو به صورت متن ساده داخل دیتابیس ذخیره کنه. سرور باید رمز رو با الگوریتم مناسب Hash کنه و فقط Hash اون رو نگه داره. هنگام ورود، سرور رمز واردشده رو دوباره با همون روش بررسی می‌کنه و نتیجه رو با Hash ذخیره‌شده مقایسه می‌کنه.

اپلیکیشن اندروید مسئول پیاده‌سازی Hash دیتابیس سرور نیست. اما باید بدونیم که ارسال رمز به معنی ذخیره شدن مستقیم اون نیست. امنیت ورود نتیجه همکاری چند بخشه: HTTPS در مسیر انتقال، Hash مناسب در Backend، Token امن برای Session و نگهداری درست Token در گوشی. اگر یکی از این بخش‌ها اشتباه باشه، ظاهر حرفه‌ای صفحه ورود هیچ ارزشی نداره.

تفاوت ورود و ثبت‌نام در معماری

ثبت‌نام و ورود از نظر ساختار برنامه بسیار شبیه هستن. هر دو فرم دارن، به ViewModel وصل میشن، از Repository استفاده می‌کنن، درخواست Retrofit می‌فرستن و Token رو ذخیره می‌کنن. اما هدف اون‌ها فرق داره:

ثبت‌نام: ساخت حساب جدید + ایجاد Session ورود: تأیید حساب موجود + ایجاد Session

در ثبت‌نام، خطاهایی مثل تکراری بودن شماره موبایل مهم هستن. در ورود، خطای اصلی اطلاعات نادرست یا حساب غیرفعاله. این شباهت باعث نمیشه تمام کدها رو با هم قاطی کنیم. می‌تونیم بخش‌های مشترکی مثل AuthRepository و TokenStorage داشته باشیم، اما State صفحه ورود و ثبت‌نام بهتره جدا باقی بمونن؛ چون رفتار و پیام‌های اون‌ها یکسان نیست.

ورود فقط بررسی رمز نیست

در ظاهر، ورود یعنی کاربر شماره و رمز رو وارد می‌کنه و دکمه‌ای رو می‌زنه. اما پشت صحنه چند مسئولیت جدا کنار هم قرار می‌گیرن.

صفحه اطلاعات رو دریافت می‌کنه. ViewModel اعتبارسنجی اولیه و State رو مدیریت می‌کنه. Repository درخواست ورود رو به API می‌فرسته. سرور هویت کاربر رو بررسی می‌کنه. Tokenها داخل فضای امن ذخیره میشن. اطلاعات کسب‌وکار در صورت نیاز وارد Room میشن و در نهایت صفحه Home باز میشه.

مهم‌ترین نکته اینه که هیچ‌کدوم از این مسئولیت‌ها نباید داخل یک onClick شلوغ جمع بشن. صفحه نباید Token ذخیره کنه. ViewModel نباید جزئیات Retrofit رو بدونه. Retrofit نباید تصمیم بگیره بعد از ورود به کدوم صفحه بریم و Navigation هم نباید درباره رمز عبور چیزی بدونه. هر بخش فقط کار خودش رو انجام میده و نتیجه رو به بخش بعدی تحویل میده.

در نهایت، مسیر ورود قیمت‌بان رو میشه در یک جمله خلاصه کرد: کاربر با رمز هویتش رو اثبات می‌کنه، سرور Token صادر می‌کنه و برنامه با ذخیره Token، یک Session قابل ادامه می‌سازه.

درس بیست‌وسوم

بعد از ورود، برنامه چطور اطلاعات اصلی کسب‌وکار رو جمع می‌کنه و داخل یک صفحه قابل مدیریت نمایش میده؟

پنل مدیریت کسب‌وکار

ثبت‌نام و ورود فقط دروازه ورود به برنامه بودن. ارزش اصلی قیمت‌بان از جایی شروع میشه که صاحب کسب‌وکار وارد پنل مدیریت میشه و می‌تونه وضعیت فروشگاه، کالاها، قیمت‌ها و فعالیت‌های اخیر رو ببینه. بنابراین پنل مدیریت فقط یک صفحه زیبا با چند کارت و عدد نیست؛ نقطه‌ایه که اطلاعات بخش‌های مختلف برنامه کنار هم قرار می‌گیرن و به کاربر کمک می‌کنن تصمیم بگیره بعد از ورود چه کاری انجام بده.

فرض کن مدیر یک فروشگاه قیمت‌بان رو باز می‌کنه. انتظار نداره وارد صفحه‌ای خالی بشه و خودش بین چند منو بگرده تا بفهمه چه خبر شده. بهتره همان ابتدا نام کسب‌وکار، تعداد کالاها، قیمت‌هایی که امروز ثبت شدن، آخرین تغییرات و چند میان‌بر مهم رو ببینه. مثلاً از همان پنل بتونه وارد فهرست کالاها بشه، قیمت جدید ثبت کنه یا کالاهای بدون قیمت رو بررسی کنه.

در ظاهر همه این اطلاعات داخل یک صفحه نمایش داده میشن، اما ممکنه از چند منبع مختلف بیان. مشخصات کسب‌وکار از Room خوانده بشه، آمار جدید از API دریافت بشه و آخرین فعالیت‌ها هم در جدول دیگری از دیتابیس محلی قرار داشته باشن. به همین دلیل، پنل مدیریت مثال خوبی برای فهمیدن این موضوعه که ViewModel چطور چند جریان اطلاعات رو به یک State واحد تبدیل می‌کنه.

مسیر کلی صفحه به این شکله:

DashboardScreen
↓
DashboardViewModel
↓
DashboardRepository
↓
Room + API
↓
DashboardUiState
↓
DashboardScreen

صفحه فقط DashboardUiState رو می‌بینه. لازم نیست بدونه نام کسب‌وکار از Room اومده، آمار کالاها از سرور دریافت شده یا آخرین فعالیت از Cache خونده شده. ViewModel و Repository این پیچیدگی رو پشت یک وضعیت ساده پنهان می‌کنن.

پنل مدیریت چه اطلاعاتی رو نمایش میده؟

قبل از نوشتن کد باید مشخص کنیم صفحه دقیقاً برای حل چه مسئله‌ای ساخته شده. اگر هر اطلاعاتی که داریم داخل Dashboard بریزیم، خیلی زود با صفحه‌ای شلوغ و بی‌هدف روبه‌رو میشیم. پنل باید فقط اطلاعاتی رو نمایش بده که کاربر با دیدن اون‌ها بتونه وضعیت فعلی رو بفهمه یا یک اقدام مهم انجام بده.

برای نسخه ابتدایی قیمت‌بان، پنل می‌تونه شامل این اطلاعات باشه:

نام کسب‌وکار
تعداد کل کالاها
تعداد قیمت‌های ثبت‌شده امروز
تعداد کالاهای بدون قیمت
آخرین به‌روزرسانی
میان‌بر ثبت قیمت جدید
میان‌بر مشاهده کالاها

هر کدوم از این موارد باید به یک نیاز واقعی پاسخ بده. مثلاً عدد تعداد کل کالاها به تنهایی شاید خیلی مهم نباشه، اما کالاهای بدون قیمت مستقیماً یک کار ناتمام رو به مدیر نشون میده. یا آخرین به‌روزرسانی کمک می‌کنه کاربر بفهمه اطلاعاتی که می‌بینه تازه هستن یا ممکنه مربوط به چند ساعت قبل باشن. پس Dashboard نباید به انبار داده تبدیل بشه. وظیفه اون خلاصه کردن وضعیت و هدایت کاربر به اقدام بعدیه.

ساخت یک مدل واحد برای صفحه

ممکنه اطلاعات پنل از مدل‌های مختلفی بیان، اما صفحه نباید مجبور باشه با چند مدل شبکه و دیتابیس کار کنه. بهتره برای خود صفحه یک مدل اختصاصی بسازیم:

data class DashboardData(
    val businessName: String,
    val totalProducts: Int,
    val todayPrices: Int,
    val productsWithoutPrice: Int,
    val lastUpdatedAt: String
)

data class DashboardData(
    val businessName: String,
    val totalProducts: Int,
    val todayPrices: Int,
    val productsWithoutPrice: Int,
    val lastUpdatedAt: String
)

این مدل نمیگه اطلاعات از کجا اومدن. فقط میگه پنل برای نمایش خودش به چه داده‌هایی نیاز داره.

businessName نام فروشگاه رو نگه می‌داره. totalProducts تعداد کل کالاهاست. todayPrices تعداد قیمت‌هایی رو مشخص می‌کنه که امروز ثبت یا ویرایش شدن. productsWithoutPrice تعداد کالاهایی رو نشون میده که هنوز قیمت ندارن و lastUpdatedAt زمان آخرین همگام‌سازی رو نگه می‌داره. دلیل ساختن چنین مدلی اینه که مدل API یا Entity دیتابیس معمولاً براساس نیازهای لایه خودشون طراحی شدن. مثلاً پاسخ سرور ممکنه ده‌ها فیلد داشته باشه که پنل به بیشتر اون‌ها نیازی نداره. DashboardData فقط اطلاعات لازم برای همین صفحه رو نگه می‌داره.

این کار باعث میشه رابط کاربری به ساختار Backend وابسته نشه. اگر فردا نام یکی از فیلدهای API عوض شد، لازم نیست تمام کدهای صفحه رو تغییر بدیم؛ فقط تبدیل مدل‌ها در Repository اصلاح میشه.

State صفحه پنل

پنل مدیریت هم مثل ثبت‌نام و ورود، به یک State مشخص نیاز داره. اما اینجا یک تفاوت مهم وجود داره. در صفحه ورود، معمولاً یا اطلاعات ارسال میشن یا خطا نمایش داده میشه. در Dashboard ممکنه داده‌های قبلی موجود باشن، اما هم‌زمان اطلاعات جدید هم در حال دریافت باشن.

نسخه ساده State می‌تونه این باشه:

sealed interface DashboardUiState {
    data object Loading : DashboardUiState

    data class Content(
        val data: DashboardData,
        val isRefreshing: Boolean = false
    ) : DashboardUiState

    data class Error(val message: String) : DashboardUiState
}

sealed interface DashboardUiState {
    data object Loading : DashboardUiState

    data class Content(
        val data: DashboardData,
        val isRefreshing: Boolean = false
    ) : DashboardUiState

    data class Error(val message: String) : DashboardUiState
}

Loading مربوط به زمانیه که هنوز هیچ اطلاعاتی برای نمایش نداریم. Content یعنی داده‌های پنل موجودن و می‌تونیم صفحه رو نمایش بدیم. Error هم زمانی استفاده میشه که هیچ داده قابل استفاده‌ای نداریم و عملیات دریافت هم شکست خورده.

فیلد isRefreshing نکته مهم این State است. فرض کن اطلاعات کش‌شده داخل Room وجود دارن. صفحه می‌تونه همان اطلاعات رو نمایش بده، در حالی که Repository در پس‌زمینه داده‌های تازه رو از سرور می‌گیره. در این حالت نباید کل صفحه رو با Loading جایگزین کنیم. صفحه همچنان Content داره، اما isRefreshing برابر true میشه. این تفاوت بین بارگذاری اولیه و به‌روزرسانی اطلاعات موجود تجربه کاربری رو خیلی بهتر می‌کنه. کاربر هنگام هر Refresh با صفحه سفید روبه‌رو نمیشه.

پنل ابتدا اطلاعات محلی رو نمایش میده

چون در درس‌های قبلی معماری Offline First رو انتخاب کردیم، صفحه باید تا جای ممکن اطلاعات خودش رو از Room دریافت کنه. Repository می‌تونه اطلاعات محلی رو به شکل یک Flow در اختیار ViewModel قرار بده:

fun observeDashboard(): Flow<DashboardData> {
    return dashboardDao.observeDashboard()
        .map { entity -> entity.toDashboardData() }
}

fun observeDashboard(): Flow<DashboardData> {
    return dashboardDao.observeDashboard()
        .map { entity -> entity.toDashboardData() }
}

این تابع قرار نیست یک‌بار اطلاعات رو بخونه و تمام بشه. Flow یعنی هر زمان داده مربوط به پنل در Room تغییر کنه، مقدار جدید به ViewModel ارسال میشه.

dashboardDao.observeDashboard() اطلاعات خام دیتابیس رو مشاهده می‌کنه. تابع map هم هر Entity رو به DashboardData تبدیل می‌کنه؛ یعنی مدل مناسب لایه UI رو می‌سازه.

مزیت این روش اینه که صفحه مستقیماً به درخواست اینترنت وابسته نیست. اگر Repository اطلاعات جدید رو از API دریافت و داخل Room ذخیره کنه، Flow تغییر رو تشخیص میده و پنل به‌صورت خودکار به‌روز میشه. پس API مستقیماً صفحه رو تغییر نمیده. API دیتابیس محلی رو به‌روزرسانی می‌کنه و دیتابیس منبع اطلاعات صفحه باقی می‌مونه.

ViewModel اطلاعات پنل رو مشاهده می‌کنه

ViewModel باید Flow مربوط به Repository رو دریافت کنه و اون رو به State قابل استفاده برای Compose تبدیل کنه:

val uiState = repository.observeDashboard()
    .map<DashboardData, DashboardUiState> {
        DashboardUiState.Content(data = it)
    }
    .stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5_000),
        initialValue = DashboardUiState.Loading
    )

val uiState = repository.observeDashboard()
    .map<DashboardData, DashboardUiState> {
        DashboardUiState.Content(data = it)
    }
    .stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5_000),
        initialValue = DashboardUiState.Loading
    )

این یکی از مهم‌ترین کدهای این درسه، چون نشون میده اطلاعات چطور از Repository به یک State پایدار داخل ViewModel تبدیل میشن.

تابع map هر DashboardData رو داخل DashboardUiState.Content قرار میده. صفحه قرار نیست مدل خام رو دریافت کنه؛ State مشخصی می‌گیره که میگه محتوای قابل نمایش آماده است. stateIn یک Flow معمولی رو به StateFlow تبدیل می‌کنه. به این ترتیب، همیشه یک مقدار فعلی برای صفحه وجود داره و Compose می‌تونه اون رو مشاهده کنه. scope = viewModelScope یعنی این جریان داده تا زمانی فعال می‌مونه که ViewModel زنده است. initialValue هم مشخص می‌کنه قبل از دریافت اولین داده، صفحه در وضعیت Loading قرار داشته باشه.

بخش زیر رفتار اشتراک‌گذاری جریان رو کنترل می‌کنه:

started = SharingStarted.WhileSubscribed(5_000)

started = SharingStarted.WhileSubscribed(5_000)

یعنی تا زمانی که صفحه‌ای در حال مشاهده State باشه، جریان فعال می‌مونه. اگر مشاهده‌گرها از بین برن، ViewModel پنج ثانیه صبر می‌کنه و بعد در صورت نیاز جریان رو متوقف می‌کنه. این فاصله کوتاه کمک می‌کنه تغییرات موقتی مثل چرخش صفحه یا جابه‌جایی کوتاه باعث توقف و شروع مکرر Flow نشن.

دریافت اطلاعات تازه از سرور

نمایش داده‌های محلی کافی نیست. Repository باید در صورت وجود اینترنت، اطلاعات جدید رو هم دریافت کنه:

suspend fun refreshDashboard() {
    val response = api.getDashboard()
    dashboardDao.upsert(response.toEntity())
}

suspend fun refreshDashboard() {
    val response = api.getDashboard()
    dashboardDao.upsert(response.toEntity())
}

این تابع دو کار انجام میده. ابتدا api.getDashboard() آمار جدید رو از سرور می‌گیره. بعد upsert اطلاعات دریافتی رو داخل Room ذخیره یا جایگزین می‌کنه.

کلمه upsert ترکیبی از insert و update است. یعنی اگر رکورد وجود نداشته باشه، ساخته میشه و اگر قبلاً وجود داشته باشه، به‌روزرسانی میشه. نکته مهم اینه که این تابع چیزی رو مستقیماً به صفحه برنمی‌گردونه. نتیجه داخل Room ذخیره میشه و Flow قبلی تغییرات رو به ViewModel منتقل می‌کنه. این مسیر باعث میشه یک منبع اصلی اطلاعات داشته باشیم:

API
↓
Room
↓
Flow
↓
ViewModel
↓
Compose

اگر هم API و هم Room مستقیماً صفحه رو تغذیه کنن، ممکنه دو نسخه متفاوت از یک داده داخل صفحه داشته باشیم. اما وقتی Room منبع اصلیه، ترتیب تغییرات مشخص باقی می‌مونه.

اجرای Refresh هنگام باز شدن صفحه

وقتی پنل برای اولین‌بار باز میشه، ViewModel می‌تونه همگام‌سازی رو شروع کنه:

init {
    refresh()
}

init {
    refresh()
}

init هنگام ساخته شدن ViewModel اجرا میشه. اینجا فقط تابع refresh() رو صدا می‌زنیم تا منطق واقعی داخل تابع جداگانه باقی بمونه. خود Refresh داخل Coroutine انجام میشه:

fun refresh() {
    viewModelScope.launch {
        repository.refreshDashboard()
    }
}

fun refresh() {
    viewModelScope.launch {
        repository.refreshDashboard()
    }
}

چون درخواست API یک عملیات suspend و زمان‌بره، داخل viewModelScope.launch اجرا میشه.

اما این نسخه هنوز مدیریت خطا یا وضعیت Refresh نداره. در پنل واقعی باید بدونیم درخواست جدید در حال اجراست یا شکست خورده.

به‌روزرسانی بدون حذف اطلاعات قبلی

فرض کن صفحه اطلاعات کش‌شده رو نمایش میده و کاربر صفحه رو به پایین می‌کشه تا Refresh انجام بشه. در این لحظه نباید State رو به Loading تغییر بدیم، چون این کار محتوای قبلی رو از صفحه حذف می‌کنه.

بهتره یک State جدا برای وضعیت Refresh داشته باشیم:

private val _isRefreshing = MutableStateFlow(false)
val isRefreshing = _isRefreshing.asStateFlow()

private val _isRefreshing = MutableStateFlow(false)
val isRefreshing = _isRefreshing.asStateFlow()

قبل از شروع درخواست، مقدار اون روی true قرار می‌گیره و بعد از پایان عملیات دوباره false میشه:

fun refresh() {
    viewModelScope.launch {
        _isRefreshing.value = true

        try {
            repository.refreshDashboard()
        } finally {
            _isRefreshing.value = false
        }
    }
}

fun refresh() {
    viewModelScope.launch {
        _isRefreshing.value = true

        try {
            repository.refreshDashboard()
        } finally {
            _isRefreshing.value = false
        }
    }
}

بخش finally چه درخواست موفق باشه و چه خطا اتفاق بیفته، اجرا میشه. بنابراین مطمئن میشیم حالت Refresh برای همیشه روشن باقی نمی‌مونه.

اگر فقط در حالت موفق مقدار رو به false برگردونیم، ممکنه هنگام خطا نشانگر Refresh همچنان روی صفحه بچرخه.

بعد میشه اطلاعات اصلی و وضعیت Refresh رو با هم ترکیب کرد:

combine(
    repository.observeDashboard(),
    isRefreshing
) { data, refreshing ->
    DashboardUiState.Content(
        data = data,
        isRefreshing = refreshing
    )
}

combine(
    repository.observeDashboard(),
    isRefreshing
) { data, refreshing ->
    DashboardUiState.Content(
        data = data,
        isRefreshing = refreshing
    )
}

combine آخرین مقدار دو Flow رو می‌گیره و از ترکیب اون‌ها State جدید می‌سازه. در اینجا یک Flow اطلاعات پنل رو میده و Flow دوم مشخص می‌کنه به‌روزرسانی در حال انجامه یا نه.

به این ترتیب، صفحه یک State واحد دریافت می‌کنه که هم داده‌ها و هم وضعیت فعلی عملیات رو در خودش داره.

صفحه چطور State رو دریافت می‌کنه؟

در Compose، پنل StateFlow رو به شکل زیر مشاهده می‌کنه:

val uiState by viewModel.uiState.collectAsStateWithLifecycle()

val uiState by viewModel.uiState.collectAsStateWithLifecycle()

هر بار که داده Room تغییر کنه یا وضعیت Refresh عوض بشه، uiState هم به‌روز میشه و Compose فقط بخش‌های وابسته رو دوباره اجرا می‌کنه.

برای نمایش وضعیت‌های مختلف می‌تونیم از when استفاده کنیم:

when (val state = uiState) {
    DashboardUiState.Loading -> LoadingView()

    is DashboardUiState.Content ->
        DashboardContent(state.data)

    is DashboardUiState.Error ->
        ErrorView(state.message)
}

when (val state = uiState) {
    DashboardUiState.Loading -> LoadingView()

    is DashboardUiState.Content ->
        DashboardContent(state.data)

    is DashboardUiState.Error ->
        ErrorView(state.message)
}

این کد ساخت کامل صفحه نیست. فقط تصمیم اصلی رابط کاربری رو نشون میده: در هر وضعیت چه چیزی باید دیده بشه.

وقتی داده‌ای وجود نداره و هنوز منتظر دریافت اولین اطلاعاتیم، Loading نمایش داده میشه. وقتی داده آماده است، محتوای پنل نمایش داده میشه و اگر هیچ داده قابل استفاده‌ای وجود نداشته باشه، صفحه خطا دیده میشه.

نمایش اطلاعات داخل کارت‌ها

برای هر عدد پنل لازم نیست یک Composable پیچیده و جدا بنویسیم. بخش متمایز اینه که مقدارها رو از DashboardData بگیریم، نه اینکه هر کارت خودش از ViewModel یا Repository اطلاعات بخونه:

DashboardStatCard(
    title = "کالاهای بدون قیمت",
    value = data.productsWithoutPrice.toString()
)

DashboardStatCard(
    title = "کالاهای بدون قیمت",
    value = data.productsWithoutPrice.toString()
)

این کارت فقط داده دریافت می‌کنه و نمایش میده. نمی‌دونه عدد از API اومده، Room یا Cache.

این نوع Composable رو به اسم Stateless Composable می‌شناسیم؛ یعنی خودش مالک State اصلی نیست و فقط براساس ورودی‌هایی که دریافت می‌کنه UI می‌سازه.

این جداسازی باعث میشه کارت رو در جای دیگری هم استفاده کنیم، راحت‌تر Preview بگیریم و در تست‌ها مقدارهای مختلف بهش بدیم.

اگر هر کارت خودش ViewModel رو صدا بزنه، اجزای UI به معماری برنامه قفل میشن و استفاده دوباره از اون‌ها سخت‌تر میشه.

میان‌برهای پنل چطور کار می‌کنن؟

در پنل قیمت‌بان ممکنه دکمه‌هایی مثل ثبت قیمت جدید یا مشاهده کالاها وجود داشته باشن. Composable داخلی پنل نباید خودش NavController رو بشناسه. بهتره رویدادها از بیرون به اون داده بشن:

DashboardContent(
    data = state.data,
    onAddPriceClick = onAddPriceClick,
    onProductsClick = onProductsClick
)

DashboardContent(
    data = state.data,
    onAddPriceClick = onAddPriceClick,
    onProductsClick = onProductsClick
)

داخل کارت مربوط به ثبت قیمت فقط Callback اجرا میشه:

Button(onClick = onAddPriceClick) {
    Text("ثبت قیمت جدید")
}

Button(onClick = onAddPriceClick) {
    Text("ثبت قیمت جدید")
}

Callback یعنی صفحه اعلام می‌کنه چه اتفاقی افتاده، اما تصمیم نهایی درباره Navigation در لایه بالاتر گرفته میشه.

مثلاً در مقصد Navigation می‌تونیم بنویسیم:

onAddPriceClick = {
    navController.navigate("add-price")
}

onAddPriceClick = {
    navController.navigate("add-price")
}

علت این جداسازی اینه که DashboardContent وظیفه نمایش محتوای پنل رو داره، نه مدیریت مسیرهای کل برنامه. اگر Navigation رو مستقیماً داخل همه کارت‌ها پخش کنیم، Composableها وابسته و آزمایش اون‌ها سخت میشه.

نمایش نام کسب‌وکار از Session یا Room؟

ممکنه نام کسب‌وکار هم داخل پاسخ ورود وجود داشته باشه، هم در Token قرار گرفته باشه و هم داخل Room ذخیره شده باشه. سؤال اینه که صفحه باید نام رو از کجا بخونه؟

بهتره اطلاعات قابل نمایش کسب‌وکار از Room دریافت بشن. Token برای اثبات هویت و ارسال درخواست‌هاست، نه برای تغذیه مستقیم رابط کاربری. حتی اگر برخی اطلاعات داخل JWT وجود داشته باشن، استفاده مستقیم از اون‌ها برای UI وابستگی نامناسبی ایجاد می‌کنه.

نام کسب‌وکار ممکنه بعداً در سرور تغییر کنه. اگر فقط مقدار قدیمی داخل Token رو نمایش بدیم، صفحه تا زمان صدور Token جدید به‌روز نمیشه. اما اطلاعات Room رو میشه هنگام همگام‌سازی به‌روزرسانی کرد.

پس قاعده ساده اینه:

Token برای هویت و مجوز
Room برای اطلاعات قابل نمایش

این دو ممکنه بخشی از داده‌های مشابه رو داشته باشن، اما هدف اون‌ها یکسان نیست.

خطای Refresh نباید کل پنل رو نابود کنه

فرض کن داده‌های قبلی داخل Room وجود دارن، اما هنگام Refresh اینترنت قطع میشه. آیا باید تمام پنل رو حذف کنیم و فقط یک صفحه خطا نمایش بدیم؟ نه، چون هنوز اطلاعات قابل استفاده‌ای داریم.

در این وضعیت بهتره محتوای قبلی حفظ بشه و فقط یک پیام کوتاه نمایش داده بشه:

به‌روزرسانی انجام نشد؛ آخرین اطلاعات ذخیره‌شده نمایش داده میشه.

برای چنین پیام‌هایی میشه یک جریان جدا از رویدادهای موقت داشت:

private val _events = MutableSharedFlow<DashboardEvent>()
val events = _events.asSharedFlow()

private val _events = MutableSharedFlow<DashboardEvent>()
val events = _events.asSharedFlow()

State با Event فرق داره. State وضعیت فعلی و ماندگار صفحه است؛ مثلاً اطلاعات پنل یا Loading. اما Event اتفاقیه که یک‌بار رخ میده؛ مثلاً نمایش Snackbar.

در زمان خطای Refresh می‌تونیم Event بفرستیم:

_events.emit(
    DashboardEvent.ShowMessage(
        "به‌روزرسانی انجام نشد"
    )
)

_events.emit(
    DashboardEvent.ShowMessage(
        "به‌روزرسانی انجام نشد"
    )
)

صفحه این رویداد رو دریافت می‌کنه و Snackbar نمایش میده، اما محتوای پنل همچنان باقی می‌مونه.

اگر پیام موقت رو داخل State دائمی قرار بدیم، ممکنه با بازسازی صفحه دوباره نمایش داده بشه. به همین دلیل، رویدادهای یک‌بارمصرف رو معمولاً از State اصلی جدا می‌کنیم.

خالی بودن پنل با خطا فرق داره

فرض کن کسب‌وکار تازه ثبت‌نام کرده و هنوز هیچ کالایی نداره. نمایش صفر در تمام کارت‌ها از نظر فنی درسته، اما احتمالاً تجربه خوبی نیست. کاربر ممکنه ندونه قدم بعدی چیه.

این حالت خطا نیست. سرور درست کار کرده و داده‌ها هم دریافت شدن؛ فقط کسب‌وکار هنوز اطلاعاتی ثبت نکرده. به این وضعیت Empty State میگیم.

می‌تونیم داخل مدل صفحه تشخیص بدیم که داده‌ای وجود نداره:

val isEmpty: Boolean
    get() = totalProducts == 0

val isEmpty: Boolean
    get() = totalProducts == 0

اگر isEmpty درست باشه، به جای چند کارت صفر میشه یک پیام راهنما نمایش داد:

هنوز کالایی ثبت نکردی.
اولین کالای کسب‌وکارت رو اضافه کن.

بعد هم یک دکمه مستقیم برای افزودن کالا قرار بدیم.

Empty State باید کاربر رو هدایت کنه. صفحه‌ای که فقط میگه اطلاعاتی وجود ندارد عملاً مسئولیت خودش رو نصفه انجام داده.

پس سه وضعیت متفاوت داریم:

Loading:
هنوز نمی‌دونیم اطلاعات چیه.

Error:
نتونستیم اطلاعات قابل استفاده‌ای دریافت کنیم.

Empty:
اطلاعات رو دریافت کردیم، اما هنوز چیزی ثبت نشده.

تفکیک این حالت‌ها باعث میشه صفحه در هر شرایط رفتار مناسبی داشته باشه.

آیا پنل باید هر بار از سرور اطلاعات بگیره؟

اگر کاربر از صفحه پنل وارد فهرست کالاها بشه و چند ثانیه بعد برگرده، منطقی نیست هر بار تمام آمار دوباره از سرور دانلود بشن. Repository می‌تونه زمان آخرین همگام‌سازی رو بررسی کنه:

if (cacheIsExpired()) {
    refreshDashboard()
}

if (cacheIsExpired()) {
    refreshDashboard()
}

cacheIsExpired() بررسی می‌کنه از آخرین دریافت اطلاعات چقدر گذشته. مثلاً اگر کمتر از پنج دقیقه گذشته باشه، پنل می‌تونه همان داده‌های موجود رو نمایش بده. اگر اطلاعات قدیمی‌تر باشن، Refresh انجام میشه.

البته کاربر باید همیشه امکان به‌روزرسانی دستی رو داشته باشه. یعنی حتی اگر Cache هنوز معتبره، با Pull to Refresh بتونه دریافت اطلاعات جدید رو مجبور کنه.

در اینجا دوباره می‌بینیم که Cache فقط یک محل ذخیره‌سازی نیست؛ تصمیمیه درباره اینکه چه زمانی داده موجود کافی است و چه زمانی باید اطلاعات تازه بگیریم.

پنل و مجوز دسترسی

در نسخه ابتدایی قیمت‌بان شاید هر کسب‌وکار فقط یک مدیر داشته باشه. اما بعدها ممکنه یک حساب چند کارمند داشته باشه؛ مثلاً مدیر، صندوق‌دار و اپراتور ثبت قیمت.

در این صورت، همه افراد نباید تمام میان‌برها رو ببینن. مثلاً کارمند عادی شاید اجازه حذف کالا یا مدیریت کاربران رو نداشته باشه.

مدل صفحه می‌تونه مجوزهای لازم رو دریافت کنه:

val canManageProducts: Boolean
val canViewReports: Boolean

val canManageProducts: Boolean
val canViewReports: Boolean

بعد رابط کاربری براساس مجوزها بعضی گزینه‌ها رو نمایش بده:

if (data.canViewReports) {
    ReportsShortcut()
}

if (data.canViewReports) {
    ReportsShortcut()
}

اما پنهان کردن دکمه فقط برای تجربه کاربریه، نه امنیت واقعی. سرور هم باید هر درخواست رو براساس مجوز کاربر بررسی کنه.

اگر فردی با دست‌کاری برنامه مستقیماً Endpoint گزارش‌ها رو صدا زد، Backend باید درخواست غیرمجاز رو رد کنه. همان اصلی که درباره اعتبارسنجی گفتیم، اینجا هم وجود داره: اپلیکیشن رفتار مناسب رو ایجاد می‌کنه، اما تصمیم امنیتی نهایی با سروره.

خروج از حساب در پنل

پنل معمولاً جاییه که کاربر به تنظیمات یا خروج از حساب دسترسی پیدا می‌کنه. هنگام خروج، فقط رفتن به صفحه Login کافی نیست. باید Session واقعاً پاک بشه:

suspend fun logout() {
    tokenStorage.clear()
    database.clearUserData()
}

suspend fun logout() {
    tokenStorage.clear()
    database.clearUserData()
}

tokenStorage.clear() Tokenها رو حذف می‌کنه تا برنامه دیگر کاربر رو واردشده در نظر نگیره. database.clearUserData() هم اطلاعات محلی مربوط به حساب فعلی رو پاک می‌کنه.

پاک کردن داده‌های محلی مخصوصاً زمانی مهمه که چند کسب‌وکار بتونن روی یک گوشی وارد برنامه بشن. اگر داده حساب قبلی باقی بمونه، ممکنه کاربر جدید اطلاعات فروشگاه قبلی رو برای چند لحظه ببینه.

بعد از پاک شدن Session، Navigation انجام میشه:

navController.navigate("login") {
    popUpTo("home") {
        inclusive = true
    }
}

navController.navigate("login") {
    popUpTo("home") {
        inclusive = true
    }
}

با حذف مسیر قبلی از Back Stack، کاربر نمی‌تونه بعد از خروج با دکمه Back دوباره وارد پنل بشه.

پنل نقطه اتصال چند درس قبلیه

در این صفحه تقریباً تمام مفاهیم قبلی دوباره کنار هم قرار می‌گیرن. Token ذخیره‌شده باعث میشه درخواست Dashboard با هویت کاربر ارسال بشه. Retrofit اطلاعات جدید رو از سرور می‌گیره. Repository تصمیم می‌گیره داده‌ها چطور ترکیب و ذخیره بشن. Room منبع اصلی اطلاعات صفحه باقی می‌مونه. Flow تغییرات رو منتقل می‌کنه. ViewModel اون‌ها رو به UI State تبدیل می‌کنه و Compose براساس State رابط کاربری رو می‌سازه.

Offline First هم باعث میشه پنل در نبود اینترنت کاملاً خالی نشه. Cache مشخص می‌کنه چه زمانی داده موجود کافی است. Error Handling هم اجازه میده خطای Refresh بدون نابود کردن محتوای قبلی مدیریت بشه.

در ظاهر، کاربر فقط چند کارت و دکمه می‌بینه؛ اما پشت این صفحه، معماری برنامه واقعاً شروع به کار کرده.

پنل مدیریت فقط نمایش اطلاعات نیست

یک Dashboard خوب باید در چند ثانیه به سه سؤال پاسخ بده:

الان وضعیت کسب‌وکار من چطوره؟
چه چیزی نیاز به توجه داره؟
قدم بعدی من چیه؟

اگر پنل فقط چند عدد بی‌معنی نمایش بده، حتی اگر از نظر فنی بی‌نقص باشه، کار خودش رو درست انجام نداده. اطلاعات باید انتخاب و اولویت‌بندی بشن تا کاربر بتونه تصمیم بگیره.

در قیمت‌بان، نمایش کالاهای بدون قیمت احتمالاً از نمایش تعداد کل درخواست‌های API ارزشمندتره؛ چون اولی یک اقدام مشخص جلوی کاربر می‌ذاره و دومی بیشتر برای توسعه‌دهنده معنا داره.

پس طراحی پنل فقط مسئله Compose و کارت‌ها نیست. مهم‌تر از اون، انتخاب اطلاعاتیه که برای صاحب کسب‌وکار واقعاً ارزش دارن.

در نهایت، مسیر پنل مدیریت قیمت‌بان رو میشه این‌طور خلاصه کرد:

Repository اطلاعات جدید رو از سرور می‌گیره و داخل Room ذخیره می‌کنه، ViewModel داده‌های محلی رو به یک State قابل فهم تبدیل می‌کنه و پنل براساس همان State، وضعیت کسب‌وکار و اقدام‌های مهم رو به کاربر نمایش میده.

درس بیست‌وچهارم

وقتی کاربر اطلاعات کسب‌وکارش رو تغییر میده، برنامه چطور مطمئن میشه داده جدید درست ذخیره شده و همه‌جای اپ به‌روز شده؟

ویرایش اطلاعات کسب‌وکار

در پنل مدیریت، اطلاعاتی مثل نام کسب‌وکار، شماره تماس، آدرس یا توضیحات فروشگاه نمایش داده میشن. اما این اطلاعات ثابت نیستن. ممکنه نام فروشگاه تغییر کنه، شعبه جابه‌جا بشه یا کاربر بخواد شماره تماس جدیدی ثبت کنه. بنابراین برنامه باید صفحه‌ای داشته باشه که اطلاعات فعلی رو نمایش بده، اجازه تغییر اون‌ها رو بده و نسخه جدید رو به‌درستی داخل سرور و حافظه محلی ذخیره کنه.

در ظاهر، ویرایش اطلاعات خیلی ساده به نظر میرسه. چند TextField داریم که مقدارهای قبلی داخلشون قرار گرفتن و یک دکمه ذخیره تغییرات هم پایین صفحه دیده میشه. اما پشت این فرم چند مسئله مهم وجود داره. اطلاعات اولیه از کجا میان؟ چطور تشخیص بدیم کاربر واقعاً چیزی رو تغییر داده؟ اگه اینترنت وسط ذخیره قطع شد، با اطلاعات داخل Room چه کار کنیم؟ و بعد از ذخیره موفق، چطور کاری کنیم نام جدید کسب‌وکار در پنل هم فوراً دیده بشه؟

مسیر کلی ویرایش به این شکله:

EditBusinessScreen
↓
EditBusinessViewModel
↓
BusinessRepository
↓
API
↓
Room
↓
Flow
↓
Dashboard و Profile

این مسیر نشون میده ویرایش اطلاعات فقط مربوط به یک فرم نیست. وقتی اطلاعات جدید ذخیره میشن، همه صفحه‌هایی که اطلاعات کسب‌وکار رو از Room مشاهده می‌کنن باید به‌صورت خودکار نسخه جدید رو دریافت کنن.

اطلاعات اولیه فرم از کجا میان؟

وقتی صفحه ویرایش باز میشه، نباید فیلدها خالی باشن. کاربر انتظار داره اطلاعات فعلی کسب‌وکار داخل فرم دیده بشن تا فقط بخش موردنظر رو تغییر بده.

چون در معماری قیمت‌بان، Room منبع اصلی اطلاعات قابل نمایش حسابه، ViewModel اطلاعات فعلی رو از Repository دریافت می‌کنه:

repository.observeBusiness()

repository.observeBusiness()

این کد یک جریان از اطلاعات کسب‌وکار برمی‌گردونه. هر زمان اطلاعات داخل Room تغییر کنن، مقدار جدید هم به ViewModel میرسه.

اما یک فرم ویرایش با یک صفحه نمایشی عادی فرق داره. در صفحه پنل می‌تونیم مستقیم اطلاعات Flow رو نمایش بدیم، اما در فرم ویرایش، کاربر باید بتونه مقدارها رو تغییر بده. بنابراین باید نسخه‌ای قابل ویرایش از اطلاعات داخل State صفحه بسازیم.

مثلاً اطلاعات اصلی کسب‌وکار ممکنه چنین مدلی داشته باشن:

data class Business(
    val id: Long,
    val name: String,
    val phone: String,
    val address: String
)

data class Business(
    val id: Long,
    val name: String,
    val phone: String,
    val address: String
)

این مدل وضعیت فعلی کسب‌وکار رو نمایش میده، اما فرم به State مخصوص خودش نیاز داره:

data class EditBusinessForm(
    val name: String = "",
    val phone: String = "",
    val address: String = ""
)

data class EditBusinessForm(
    val name: String = "",
    val phone: String = "",
    val address: String = ""
)

علت جدا کردن این دو مدل اینه که مدل Business نماینده اطلاعات ذخیره‌شده و معتبر برنامه است، اما EditBusinessForm اطلاعاتیه که کاربر هنوز ممکنه در حال تایپ کردن یا ناقص وارد کردنشون باشه.

مثلاً کاربر هنگام ویرایش شماره تماس ممکنه برای چند ثانیه فیلد رو کاملاً پاک کنه تا شماره جدید رو بنویسه. این مقدار خالی هنوز نباید به‌عنوان اطلاعات معتبر کسب‌وکار داخل Room ذخیره بشه، اما برای State موقت فرم کاملاً طبیعیه.

چرا فرم باید داخل ViewModel نگهداری بشه؟

در فرم ثبت‌نام، اطلاعات اولیه هنوز وجود نداشتن و می‌تونستیم مقدار فیلدها رو با rememberSaveable داخل خود صفحه نگه داریم. اما در صفحه ویرایش، فرم از داده‌ای ساخته میشه که از Room میاد و ممکنه در فرایندهای مختلف تغییر کنه.

در اینجا نگهداری State فرم داخل ViewModel می‌تونه کنترل بیشتری ایجاد کنه:

private val _form = MutableStateFlow(EditBusinessForm())
val form = _form.asStateFlow()

private val _form = MutableStateFlow(EditBusinessForm())
val form = _form.asStateFlow()

نسخه خصوصی _form فقط داخل ViewModel تغییر می‌کنه. صفحه نسخه عمومی form رو مشاهده می‌کنه و مقدار فیلدها رو نمایش میده.

وقتی اطلاعات اصلی کسب‌وکار دریافت میشن، ViewModel اون‌ها رو وارد فرم می‌کنه:

_form.value = EditBusinessForm(
    name = business.name,
    phone = business.phone,
    address = business.address
)

_form.value = EditBusinessForm(
    name = business.name,
    phone = business.phone,
    address = business.address
)

این کد اطلاعات ذخیره‌شده رو به State قابل ویرایش صفحه تبدیل می‌کنه.

اما باید مراقب یک مشکل مهم باشیم. اگه Flow مربوط به اطلاعات کسب‌وکار چند بار مقدار جدید منتشر کنه، ممکنه فرم کاربر وسط تایپ دوباره با اطلاعات قبلی پر بشه و تغییراتش از بین برن. بنابراین معمولاً فرم رو فقط یک‌بار، هنگام دریافت اولین اطلاعات، مقداردهی می‌کنیم.

مثلاً می‌تونیم بررسی کنیم آیا فرم قبلاً مقداردهی شده یا نه:

if (!_isFormInitialized) {
    _form.value = business.toEditForm()
    _isFormInitialized = true
}

if (!_isFormInitialized) {
    _form.value = business.toEditForm()
    _isFormInitialized = true
}

این شرط باعث میشه اطلاعات اولیه فقط یک‌بار داخل فرم قرار بگیرن. بعد از اون، تغییرات کاربر حفظ میشن و هر انتشار جدید Flow فرم رو بازنشانی نمی‌کنه.

تغییر هر فیلد چطور وارد ViewModel میشه؟

صفحه نباید مستقیماً مقدار StateFlow رو تغییر بده. برای هر تغییر، یک رویداد به ViewModel می‌فرسته:

viewModel.onNameChanged(newValue)

viewModel.onNameChanged(newValue)

داخل ViewModel فقط همان قسمت فرم تغییر می‌کنه:

fun onNameChanged(value: String) {
    _form.update { current ->
        current.copy(name = value)
    }
}

fun onNameChanged(value: String) {
    _form.update { current ->
        current.copy(name = value)
    }
}

تابع update مقدار فعلی StateFlow رو می‌گیره و نسخه جدیدی از اون می‌سازه. copy هم فقط فیلد name رو تغییر میده و شماره تماس و آدرس رو دست‌نخورده نگه می‌داره.

این روش از تغییر مستقیم و پراکنده State جلوگیری می‌کنه. همه تغییرات فرم از مسیر ViewModel عبور می‌کنن و اگه بعدها بخوایم محدودیت یا پردازشی اضافه کنیم، محل اون مشخصه.

مثلاً برای شماره تماس می‌تونیم فقط عددها رو بپذیریم:

fun onPhoneChanged(value: String) {
    _form.update {
        it.copy(phone = value.filter(Char::isDigit))
    }
}

fun onPhoneChanged(value: String) {
    _form.update {
        it.copy(phone = value.filter(Char::isDigit))
    }
}

filter(Char::isDigit) تمام کاراکترهایی رو که عدد نیستن حذف می‌کنه. بنابراین اگه کاربر فاصله، خط تیره یا حرف وارد کنه، فقط رقم‌ها داخل State باقی می‌مونن.

البته این تصمیم به نوع شماره تماس بستگی داره. برای شماره‌های بین‌المللی ممکنه به علامت + نیاز داشته باشیم. بنابراین نباید هر محدودیتی رو بدون توجه به نیاز واقعی پروژه وارد کنیم.

آیا واقعاً چیزی تغییر کرده؟

یکی از مشکلات رایج صفحه ویرایش اینه که دکمه ذخیره همیشه فعاله، حتی وقتی کاربر هیچ تغییری نداده. در این حالت با هر کلیک یک درخواست بیهوده به سرور ارسال میشه.

برای تشخیص تغییر، باید نسخه اولیه اطلاعات رو هم نگه داریم:

private var originalForm: EditBusinessForm? = null

private var originalForm: EditBusinessForm? = null

وقتی اطلاعات اولیه دریافت میشن، هم فرم فعلی و هم نسخه اصلی رو ذخیره می‌کنیم:

val initialForm = business.toEditForm()

_form.value = initialForm
originalForm = initialForm

val initialForm = business.toEditForm()

_form.value = initialForm
originalForm = initialForm

حالا می‌تونیم بررسی کنیم فرم فعلی با نسخه اصلی فرق داره یا نه:

val hasChanges: Boolean
    get() = _form.value != originalForm

val hasChanges: Boolean
    get() = _form.value != originalForm

چون EditBusinessForm یک data class است، Kotlin مقدار فیلدهای اون رو مقایسه می‌کنه. اگه حتی یکی از فیلدها تغییر کرده باشه، نتیجه مقایسه متفاوت میشه.

این مقدار می‌تونه برای فعال یا غیرفعال کردن دکمه ذخیره استفاده بشه:

enabled = uiState.hasChanges && !uiState.isSaving

enabled = uiState.hasChanges && !uiState.isSaving

یعنی دکمه فقط زمانی فعال باشه که چیزی تغییر کرده و عملیات ذخیره هم در حال انجام نباشه.

این رفتار هم تعداد درخواست‌های غیرضروری رو کمتر می‌کنه و هم به کاربر نشون میده هنوز تغییری برای ذخیره وجود نداره.

State صفحه ویرایش

برای این صفحه، فقط Loading و Success کافی نیست. ما هم اطلاعات فرم رو داریم، هم وضعیت بارگذاری اولیه، هم وضعیت ذخیره و هم احتمال خطا.

یک State مناسب می‌تونه چنین ساختاری داشته باشه:

data class EditBusinessUiState(
    val form: EditBusinessForm = EditBusinessForm(),
    val isLoading: Boolean = true,
    val isSaving: Boolean = false,
    val hasChanges: Boolean = false,
    val errorMessage: String? = null
)

data class EditBusinessUiState(
    val form: EditBusinessForm = EditBusinessForm(),
    val isLoading: Boolean = true,
    val isSaving: Boolean = false,
    val hasChanges: Boolean = false,
    val errorMessage: String? = null
)

در این صفحه چند وضعیت می‌تونن هم‌زمان وجود داشته باشن. مثلاً فرم نمایش داده بشه و هم‌زمان isSaving هم درست باشه. به همین دلیل، برخلاف Login که Stateهای جداگانه مثل Loading و Success داشت، اینجا یک data class می‌تونه مناسب‌تر باشه.

form اطلاعات فعلی فیلدها رو نگه می‌داره. isLoading مربوط به دریافت اطلاعات اولیه است. isSaving نشون میده درخواست ذخیره در حال اجراست. hasChanges برای کنترل دکمه ذخیره استفاده میشه و errorMessage هم خطای فعلی فرم یا سرور رو نگه می‌داره.

این مثال نشون میده هیچ قانونی وجود نداره که تمام صفحه‌ها حتماً باید از sealed interface استفاده کنن. شکل State باید براساس ماهیت صفحه انتخاب بشه.

وقتی حالت‌ها انحصاری هستن، مثل Login، sealed interface خیلی مناسبه. اما وقتی چند ویژگی می‌تونن هم‌زمان فعال باشن، data class معمولاً خواناتر میشه.

اعتبارسنجی قبل از ذخیره

قبل از ارسال اطلاعات جدید، باید بررسی کنیم مقدارها معتبر باشن:

if (form.name.isBlank()) {
    showError("نام کسب‌وکار رو وارد کن")
    return
}

if (form.name.isBlank()) {
    showError("نام کسب‌وکار رو وارد کن")
    return
}

isBlank() رشته خالی یا رشته‌ای که فقط فاصله داره رو نامعتبر تشخیص میده.

برای شماره تماس هم می‌تونیم حداقل ساختار رو بررسی کنیم:

if (form.phone.length < 10) {
    showError("شماره تماس معتبر نیست")
    return
}

if (form.phone.length < 10) {
    showError("شماره تماس معتبر نیست")
    return
}

این فقط یک نمونه ساده است. قانون دقیق باید براساس نوع شماره‌های قابل قبول در قیمت‌بان نوشته بشه.

آدرس ممکنه اختیاری باشه. بنابراین نباید صرفاً چون خالیه، جلوی ذخیره رو بگیریم؛ مگر اینکه نیاز واقعی سیستم این باشه که هر کسب‌وکار حتماً آدرس داشته باشه.

اعتبارسنجی باید از قوانین کسب‌وکار بیاد، نه از سلیقه برنامه‌نویس. هر فیلدی که روی صفحه هست الزاماً اجباری نیست.

مدل درخواست ویرایش

در ثبت‌نام از RegisterRequest استفاده کردیم. برای ویرایش هم بهتره مدل مخصوص درخواست داشته باشیم:

data class UpdateBusinessRequest(
    val name: String,
    val phone: String,
    val address: String?
)

این مدل قرارداد بین اپلیکیشن و Endpoint ویرایشه.

ممکنه در مدل اصلی Business ده‌ها فیلد وجود داشته باشه، اما Endpoint ویرایش فقط همین سه فیلد رو دریافت کنه. ارسال کل مدل کسب‌وکار هم درخواست رو سنگین‌تر می‌کنه و هم احتمال تغییر ناخواسته فیلدهایی رو بالا می‌بره که کاربر اصلاً به اون‌ها دسترسی نداره.

به همین دلیل بهتره هر درخواست مدل مخصوص خودش رو داشته باشه.

اگر سرور برای نام کسب‌وکار از نام متفاوتی استفاده کنه، مثل business_name، دوباره از Annotation مربوط به Serialization استفاده می‌کنیم:

@SerialName("business_name")
val name: String

این خط به Serialization میگه نام Kotlin برابر name است، اما در JSON باید با کلید business_name ارسال بشه.

درخواست Retrofit برای ویرایش

برای ویرایش کامل یک منبع، معمولاً از PUT و برای ویرایش بخشی از اطلاعات، معمولاً از PATCH استفاده میشه. انتخاب دقیق به طراحی API بستگی داره.

مثلاً اگه فقط فیلدهای ارسال‌شده تغییر کنن، Endpoint می‌تونه چنین باشه:

@PATCH("business/profile")
suspend fun updateBusiness(
    @Body request: UpdateBusinessRequest
): BusinessDto

@PATCH یعنی قرار نیست کل موجودیت کسب‌وکار از نو جایگزین بشه؛ فقط بخش‌هایی که در درخواست تعریف شدن تغییر می‌کنن.

خروجی BusinessDto هم نسخه جدید اطلاعات کسب‌وکاره که سرور بعد از ذخیره برمی‌گردونه.

این موضوع خیلی مهمه. نباید فرض کنیم چون درخواست موفق بوده، دقیقاً همان داده‌ای که فرستادیم باید داخل Room ذخیره بشه. سرور ممکنه داده رو اصلاح یا استاندارد کرده باشه. مثلاً فاصله‌های اضافی نام رو حذف کرده باشه، شماره رو به قالب استاندارد تبدیل کرده باشه یا زمان آخرین ویرایش رو تغییر داده باشه.

بنابراین بهتره نسخه نهایی اطلاعات رو از پاسخ سرور دریافت کنیم.

Repository چطور اطلاعات رو ذخیره می‌کنه؟

بخش متمایز Repository چنین مسیری داره:

val updatedBusiness = api.updateBusiness(
    UpdateBusinessRequest(
        name = form.name.trim(),
        phone = form.phone.trim(),
        address = form.address.trim().ifBlank { null }
    )
)

نام و شماره قبل از ارسال trim() میشن تا فاصله‌های ناخواسته ابتدا و انتهای اون‌ها حذف بشن.

برای آدرس از این بخش استفاده کردیم:

form.address.trim().ifBlank { null }

اول فاصله‌ها حذف میشن. بعد اگه نتیجه کاملاً خالی باشه، به جای رشته خالی، مقدار null ارسال میشه.

فرق رشته خالی و null در بعضی APIها مهمه. رشته خالی یعنی فیلد وجود داره، اما مقدارش خالیه. null می‌تونه به معنی آدرسی ثبت نشده باشه. قرارداد دقیق این رفتار باید با Backend هماهنگ باشه.

بعد از دریافت پاسخ، نسخه جدید داخل Room ذخیره میشه:

businessDao.upsert(
    updatedBusiness.toEntity()
)

این خط نقطه اصلی هماهنگی برنامه است. سرور اطلاعات رو تغییر داده و حالا نسخه تأییدشده داخل دیتابیس محلی ذخیره میشه.

از این لحظه، تمام Flowهایی که اطلاعات کسب‌وکار رو مشاهده می‌کنن مقدار جدید رو دریافت می‌کنن. بنابراین نام جدید فقط داخل صفحه ویرایش دیده نمیشه؛ پنل مدیریت، صفحه پروفایل و هر بخش وابسته دیگری هم خودکار به‌روز میشن.

چرا ابتدا Room رو تغییر ندیم؟

ممکنه به نظر برسه بهتره به محض زدن دکمه ذخیره، اطلاعات جدید رو فوراً داخل Room بنویسیم و بعد درخواست سرور رو در پس‌زمینه انجام بدیم. این روش به‌عنوان Optimistic Update شناخته میشه.

در بعضی عملیات‌ها Optimistic Update تجربه خیلی خوبی ایجاد می‌کنه، اما برای اطلاعات اصلی حساب باید محتاط باشیم. اگه شماره تماس تکراری باشه یا سرور نام جدید رو رد کنه، مجبور میشیم تغییر محلی رو برگردونیم.

در نسخه ساده‌تر و امن‌تر، ابتدا درخواست رو برای سرور می‌فرستیم و فقط بعد از موفقیت، Room رو به‌روزرسانی می‌کنیم:

فرم
 ↓
سرور
 ↓
پاسخ موفق
 ↓
Room
 ↓
UI

این روش کمی کندتر به نظر میرسه، اما اطلاعات محلی همیشه نسخه تأییدشده سرور باقی می‌مونه.

برای تغییرات کم‌ریسک، مثل روشن یا خاموش کردن یک تنظیم ظاهری، Optimistic Update می‌تونه مناسب باشه. اما برای اطلاعات هویتی یا حساس، دریافت تأیید سرور معمولاً مطمئن‌تره.

ذخیره اطلاعات داخل ViewModel

هنگام کلیک روی دکمه، ViewModel ابتدا فرم رو می‌خونه و اعتبارسنجی می‌کنه. بعد وضعیت ذخیره رو فعال می‌کنه:

_uiState.update {
    it.copy(
        isSaving = true,
        errorMessage = null
    )
}

isSaving = true باعث میشه دکمه غیرفعال بشه و Loading نمایش داده بشه. errorMessage = null هم خطای قبلی رو پاک می‌کنه تا پیام قدیمی هنگام تلاش جدید روی صفحه باقی نمونه.

سپس درخواست داخل Coroutine اجرا میشه:

viewModelScope.launch {
    try {
        repository.updateBusiness(uiState.value.form)
        onSaveSuccess()
    } catch (error: Exception) {
        onSaveError(error)
    }
}

ViewModel فرم رو به Repository تحویل میده. Repository اون رو به مدل درخواست تبدیل می‌کنه، API رو صدا می‌زنه و پاسخ رو داخل Room ذخیره می‌کنه.

اگه همه مراحل موفق باشن، تابع موفقیت اجرا میشه. اگه خطایی اتفاق بیفته، State خطا به‌روزرسانی میشه.

بعد از ذخیره موفق چه اتفاقی می‌افته؟

پس از ذخیره موفق، باید نسخه اصلی فرم رو هم به اطلاعات جدید تغییر بدیم. وگرنه برنامه همچنان فکر می‌کنه فرم نسبت به نسخه اولیه تغییر کرده.

originalForm = _form.value

بعد وضعیت ذخیره خاموش میشه و hasChanges هم به false برمی‌گرده:

_uiState.update {
    it.copy(
        isSaving = false,
        hasChanges = false
    )
}

حالا می‌تونیم یک پیام موفقیت نمایش بدیم:

اطلاعات کسب‌وکار ذخیره شد.

این پیام یک اتفاق موقته، نه State دائمی صفحه. بنابراین میشه مثل درس قبل، از SharedFlow برای رویدادها استفاده کرد:

_events.emit(EditBusinessEvent.Saved)

صفحه رویداد Saved رو دریافت می‌کنه و می‌تونه Snackbar نمایش بده یا به صفحه قبل برگرده.

بعد از ذخیره، صفحه بسته بشه یا باز بمونه؟

این تصمیم به تجربه کاربری بستگی داره.

اگه صفحه فقط برای یک ویرایش سریع باز شده، بعد از ذخیره موفق می‌تونه بسته بشه:

navController.popBackStack()

popBackStack() کاربر رو به صفحه قبلی برمی‌گردونه.

اما اگه صفحه تنظیمات چند بخش مختلف داره و کاربر ممکنه بخواد تغییرات بیشتری انجام بده، بهتره صفحه باز بمونه و فقط پیام موفقیت نمایش داده بشه.

برای قیمت‌بان، اگه صفحه‌ای مستقل با عنوان ویرایش اطلاعات کسب‌وکار داشته باشیم، برگشت خودکار بعد از ذخیره می‌تونه رفتار مناسبی باشه. چون کاربر وارد صفحه شده، تغییر رو انجام داده و کارش تمام شده.

اما تصمیم نباید تصادفی باشه. باید ببینیم کاربر بعد از ذخیره معمولاً چه کاری انجام میده.

مدیریت خطای شماره تماس تکراری

ممکنه کاربر شماره‌ای وارد کنه که قبلاً برای کسب‌وکار دیگری ثبت شده. سرور احتمالاً درخواست رو با کد 409 Conflict رد می‌کنه.

این خطا باید به پیام مشخص تبدیل بشه:

is DuplicatePhoneException ->
    "این شماره تماس قبلاً برای حساب دیگری ثبت شده"

این خطا بهتره نزدیک همان فیلد شماره تماس نمایش داده بشه، نه فقط به شکل یک پیام عمومی بالای صفحه.

برای این کار می‌تونیم خطاهای فیلدها رو داخل State فرم نگه داریم:

data class EditBusinessFormErrors(
    val name: String? = null,
    val phone: String? = null,
    val address: String? = null
)

وقتی خطای شماره رخ میده، فقط خطای همان فیلد تغییر می‌کنه:

errors.copy(
    phone = "این شماره قبلاً ثبت شده"
)

در Compose هم TextField می‌تونه این خطا رو نمایش بده:

isError = state.errors.phone != null

این خط میگه اگه برای شماره تماس پیام خطایی وجود داره، TextField باید در حالت خطا نمایش داده بشه.

پیام واقعی هم از State گرفته میشه:

supportingText = {
    state.errors.phone?.let {
        Text(it)
    }
}

این تجربه خیلی بهتر از نمایش یک پیام مبهم در پایین صفحه است، چون کاربر دقیقاً می‌فهمه کدام فیلد نیاز به اصلاح داره.

خطای سرور نباید تغییرات فرم رو پاک کنه

فرض کن کاربر نام، شماره و آدرس رو تغییر داده و بعد اینترنت قطع میشه. اگه هنگام خطا فرم دوباره از Room مقداردهی بشه، تمام چیزهایی که تایپ کرده از بین میرن.

این رفتار آزاردهنده است. در زمان خطای ذخیره، فرم باید همان‌طور باقی بمونه و فقط پیام خطا نمایش داده بشه:

_uiState.update {
    it.copy(
        isSaving = false,
        errorMessage = error.toUserMessage()
    )
}

در اینجا هیچ تغییری در form انجام نمیدیم. بنابراین کاربر فقط بعد از اتصال اینترنت دوباره روی ذخیره می‌زنه و لازم نیست همه اطلاعات رو از اول وارد کنه.

این یکی از مهم‌ترین تفاوت‌های State فرم و داده ذخیره‌شده است. فرم ممکنه نسخه‌ای هنوز تأییدنشده داشته باشه و باید تا زمان تصمیم کاربر حفظ بشه.

اگه کاربر بدون ذخیره خارج بشه چه کنیم؟

فرض کن کاربر نام کسب‌وکار رو تغییر داده، اما قبل از زدن دکمه ذخیره روی Back می‌زنه. اگه فوراً از صفحه خارج بشیم، تغییراتش از بین میرن.

چون hasChanges رو داریم، می‌تونیم قبل از خروج بررسی کنیم:

if (uiState.hasChanges) {
    showDiscardChangesDialog()
} else {
    navController.popBackStack()
}

اگه تغییری وجود نداشته باشه، صفحه عادی بسته میشه. اما اگه فرم تغییر کرده باشه، یک Dialog نمایش داده میشه:

تغییرات ذخیره نشدن.
می‌خوای بدون ذخیره از صفحه خارج بشی؟

این Dialog معمولاً دو انتخاب داره: ادامه ویرایش و خروج بدون ذخیره.

این رفتار جلوی از بین رفتن ناخواسته اطلاعات رو می‌گیره، مخصوصاً وقتی فرم طولانیه.

البته نباید برای هر تغییر کوچکی کاربر رو با هشدارهای زیاد اذیت کنیم. اما برای فرمی که اطلاعات مهم کسب‌وکار رو تغییر میده، هشدار خروج منطقیه.

ویرایش در حالت آفلاین

در معماری Offline First، ممکنه به ذهنمون برسه که ویرایش اطلاعات کسب‌وکار رو هم آفلاین انجام بدیم و بعداً با سرور همگام کنیم.

از نظر فنی این کار ممکنه. می‌تونیم تغییرات رو داخل Room ثبت کنیم و یک وضعیت مثل pendingSync روی رکورد قرار بدیم. بعد وقتی اینترنت وصل شد، WorkManager اطلاعات رو به سرور بفرسته.

اما این روش چند مسئله ایجاد می‌کنه. ممکنه شماره جدید در سرور تکراری باشه. ممکنه کاربر هم‌زمان از دستگاه دیگری اطلاعات رو تغییر داده باشه. یا سرور بخشی از داده رو رد کنه.

برای نسخه ابتدایی قیمت‌بان، بهتره اطلاعات هویتی و اصلی حساب فقط با اتصال اینترنت و تأیید سرور تغییر کنن. در نبود اینترنت، اطلاعات فرم حفظ میشن، اما ذخیره نهایی انجام نمیشه.

پیام مناسب می‌تونه این باشه:

برای ذخیره تغییرات، اتصال اینترنت لازمه.
اطلاعاتی که وارد کردی حفظ شده.

این هم رفتار صادقانه‌ایه و هم پیچیدگی Sync و تعارض داده رو وارد نسخه اولیه نمی‌کنه.

تغییر شماره تماس ممکنه با تغییر عادی فرق داشته باشه

گاهی شماره تماس فقط یک فیلد ساده نیست و نقش شناسه ورود کاربر رو هم داره. در این حالت تغییر شماره باید با حساسیت بیشتری انجام بشه.

ممکنه سرور بعد از وارد کردن شماره جدید، یک کد تأیید ارسال کنه. تا زمانی که شماره تأیید نشده، نباید شماره قبلی جایگزین بشه.

مسیر چنین تغییری می‌تونه به این شکل باشه:

شماره جدید
 ↓
ارسال کد تأیید
 ↓
تأیید کد
 ↓
تغییر شماره در سرور
 ↓
به‌روزرسانی Room

در این حالت، قرار دادن شماره کنار نام و آدرس در یک درخواست عمومی ویرایش چندان مناسب نیست. بهتره Endpoint و فرایند جداگانه‌ای داشته باشه.

این مثال نشون میده ظاهر مشابه فیلدها همیشه به معنی منطق مشابه نیست. نام فروشگاه رو میشه مستقیم تغییر داد، اما شماره‌ای که برای ورود استفاده میشه ممکنه نیاز به تأیید هویت دوباره داشته باشه.

آیا Token هم باید بعد از ویرایش تغییر کنه؟

اگه Token فقط شامل شناسه کاربر و سطح دسترسی باشه، تغییر نام کسب‌وکار نیازی به Token جدید نداره. اطلاعات جدید از Room نمایش داده میشن.

اما اگه اطلاعاتی مثل نام، شماره یا نقش کاربر داخل Claims مربوط به JWT قرار گرفته باشن، Token قدیمی ممکنه همچنان داده قبلی رو داشته باشه.

به همین دلیل بهتره UI اطلاعات قابل نمایش رو مستقیم از Token نخونه. Token باید برای اثبات هویت و مجوز استفاده بشه، نه برای نگهداری آخرین نسخه پروفایل.

در بعضی سیستم‌ها، سرور بعد از تغییر اطلاعات حساس Token جدید هم صادر می‌کنه:

response.newAccessToken?.let {
    tokenStorage.saveAccessToken(it)
}

این کد میگه اگه پاسخ ویرایش شامل Access Token جدید بود، نسخه قبلی جایگزین بشه.

اما این رفتار باید فقط وقتی اجرا بشه که Backend واقعاً چنین قراردادی داشته باشه. نباید خودمون بدون نیاز Token جدید بسازیم یا انتظار داشته باشیم.

همه صفحه‌ها چطور به‌روز میشن؟

زیبایی مسیر Room و Flow اینجا مشخص میشه. Repository پاسخ موفق سرور رو داخل Room ذخیره می‌کنه:

businessDao.upsert(updatedBusiness.toEntity())

صفحه پنل از قبل چنین جریانی رو مشاهده می‌کنه:

repository.observeBusiness()

وقتی رکورد Room تغییر می‌کنه، Flow مقدار جدید رو منتشر می‌کنه. DashboardViewModel مقدار جدید رو دریافت می‌کنه و Compose نام جدید رو نمایش میده.

بنابراین لازم نیست بعد از بازگشت از صفحه ویرایش، دستی بگیم:

نام پنل رو تغییر بده.
پروفایل رو Refresh کن.
منوی کناری رو دوباره بساز.

همه این صفحه‌ها به یک منبع مشترک وصل هستن و تغییر از همان منبع منتشر میشه.

این یکی از مزیت‌های مهم معماری واکنشی است:

به جای اینکه صفحه‌ها رو دستی به‌روز کنیم، داده اصلی رو تغییر میدیم و صفحه‌ها خودشان به تغییر واکنش نشون میدن.

تفاوت منبع داده و State فرم

در این درس دو نوع State داشتیم که نباید با هم اشتباه گرفته بشن.

Room نسخه تأییدشده و ذخیره‌شده اطلاعات کسب‌وکار رو نگه می‌داره. اما فرم نسخه‌ای موقتی و قابل تغییر داره که ممکنه هنوز اشتباه، ناقص یا ذخیره‌نشده باشه.

مسیر عادی به این شکله:

Room
 ↓
اطلاعات اولیه فرم
 ↓
تغییرات کاربر
 ↓
اعتبارسنجی
 ↓
API
 ↓
پاسخ تأییدشده
 ↓
Room

اطلاعات فقط یک‌بار از Room وارد فرم میشن. بعد کاربر نسخه موقتی خودش رو تغییر میده. اگه سرور تغییر رو تأیید کرد، نسخه جدید دوباره وارد Room میشه.

این جداسازی جلوی یک اشتباه خطرناک رو می‌گیره: ذخیره شدن اطلاعات ناقص فرم داخل منبع اصلی برنامه قبل از تأیید نهایی.

ویرایش اطلاعات فقط تغییر چند TextField نیست

ظاهر صفحه ویرایش شاید از صفحه ثبت‌نام ساده‌تر به نظر برسه، چون اطلاعات قبلی از قبل وجود دارن. اما از نظر مدیریت State پیچیده‌تره. باید اطلاعات اولیه رو دریافت کنیم، نسخه اصلی رو نگه داریم، تغییرات کاربر رو جدا کنیم، تغییر واقعی رو تشخیص بدیم، اعتبارسنجی انجام بدیم و فقط بعد از تأیید سرور، Room رو به‌روزرسانی کنیم.

در این فرایند، صفحه فقط فیلدها و وضعیت رو نمایش میده. ViewModel State فرم، اعتبارسنجی و عملیات ذخیره رو مدیریت می‌کنه. Repository درخواست رو به API می‌فرسته و نسخه تأییدشده رو داخل Room قرار میده. Flow هم تغییر رو به همه بخش‌های برنامه منتقل می‌کنه.

مهم‌ترین نکته این درس اینه که فرم ویرایش خودش منبع اصلی اطلاعات نیست. فرم فقط یک نسخه موقت از داده است که کاربر در حال تغییر اون است. تا وقتی سرور تغییر رو نپذیرفته، داده اصلی برنامه نباید جایگزین بشه.

در نهایت، مسیر ویرایش اطلاعات کسب‌وکار رو میشه این‌طور خلاصه کرد:

اطلاعات فعلی از Room وارد فرم میشن، کاربر یک نسخه موقت رو تغییر میده، Repository نسخه جدید رو برای سرور می‌فرسته و فقط بعد از تأیید سرور، اطلاعات داخل Room جایگزین میشن تا همه صفحه‌های برنامه به‌صورت خودکار به‌روز بشن.

درس بیست‌وپنجم

یک عکس چطور از دوربین یا گالری وارد برنامه میشه، برش می‌خوره، سبک میشه و در نهایت به سرور میرسه؟

آپلود عکس

در صفحه ویرایش اطلاعات کسب‌وکار، تغییر نام یا آدرس نسبتاً ساده بود. کاربر یک متن رو تغییر می‌داد و برنامه همون متن رو داخل یک درخواست JSON برای سرور می‌فرستاد. اما عکس با متن فرق داره. عکس ممکنه چند مگابایت حجم داشته باشه، از دوربین یا گالری وارد بشه، جهت اشتباهی داشته باشه، ابعادش بیش از حد بزرگ باشه یا بخشی از تصویر رو شامل بشه که اصلاً برای پروفایل مناسب نیست.

به همین دلیل، آپلود عکس فقط صدا زدن یک Endpoint نیست. این فرایند از چند مرحله جدا تشکیل شده:

انتخاب منبع عکس
      ↓
Camera یا Gallery
      ↓
دریافت Uri
      ↓
Crop
      ↓
Resize و Compress
      ↓
ساخت فایل قابل ارسال
      ↓
Multipart Upload
      ↓
دریافت آدرس عکس
      ↓
ذخیره در Room
      ↓
نمایش در برنامه

هر مرحله یک مسئله متفاوت رو حل می‌کنه. دوربین عکس جدید می‌سازه. گالری به یک تصویر موجود دسترسی میده. Crop محدوده مناسب تصویر رو مشخص می‌کنه. Compress حجم فایل رو کم می‌کنه و Upload نسخه نهایی رو به سرور می‌فرسته.

نکته مهم اینه که نباید تمام این مراحل رو داخل onClick دکمه تغییر عکس بنویسیم. صفحه فقط رویدادهای مربوط به انتخاب عکس رو مدیریت می‌کنه و ViewModel وضعیت فرایند رو نگه می‌داره. پردازش فایل و ارتباط با سرور هم در کلاس‌های مخصوص خودشون انجام میشه.

عکس کسب‌وکار از کجا میاد؟

وقتی کاربر روی تصویر پروفایل کسب‌وکار می‌زنه، معمولاً یک پنجره کوچک نمایش میدیم:

گرفتن عکس با دوربین
انتخاب از گالری
حذف عکس فعلی

این گزینه‌ها از نظر تجربه کاربری در کنار هم قرار دارن، اما پشت صحنه مسیر یکسانی ندارن.

در مسیر دوربین، برنامه باید قبل از باز کردن دوربین یک محل برای ذخیره عکس بسازه. دوربین تصویر گرفته‌شده رو داخل همون محل قرار میده. در مسیر گالری، خود سیستم یک Uri مربوط به عکس انتخاب‌شده رو به برنامه برمی‌گردونه.

اما بعد از این مرحله، بهتره هر دو مسیر به یک نقطه مشترک برسن:

Camera ───┐
          ├──→ Uri عکس اولیه → Crop → Compress → Upload
Gallery ──┘

یعنی بخش Crop و Upload نباید اهمیت بده عکس از دوربین اومده یا گالری. این جداسازی باعث میشه کد پردازش رو دوبار ننویسیم.

Uri دقیقاً چیه؟

در وب معمولاً با مسیرهایی مثل این سروکار داریم:

/uploads/business/logo.jpg

اما در اندروید، عکس انتخاب‌شده همیشه یک مسیر فایل مستقیم نیست. سیستم معمولاً یک Uri تحویل میده:

content://media/picker/...

Uri رو میشه شبیه یک آدرس دسترسی به محتوا در نظر گرفت. این آدرس ممکنه به یک فایل واقعی اشاره کنه، اما برنامه لازم نیست و گاهی اصلاً نباید مسیر فیزیکی اون فایل رو پیدا کنه.

اشتباه رایج اینه که توسعه‌دهنده تلاش می‌کنه هر content:// Uri رو به یک مسیر مثل /storage/emulated/0/... تبدیل کنه. این روش روی همه نسخه‌ها و همه سرویس‌های انتخاب فایل قابل اعتماد نیست. بهتره محتوا رو با ContentResolver مستقیماً از خود Uri بخونیم.

پس در این درس، Uri حلقه اتصال تمام مراحل پردازشه:

عکس انتخاب‌شده → Uri
عکس گرفته‌شده → Uri
خروجی Crop → Uri یا File
فایل فشرده‌شده → File

انتخاب عکس از گالری

برای انتخاب عکس، روش جدیدتر و مناسب‌تر اندروید استفاده از Photo Picker سیستمه. این انتخابگر به کاربر اجازه میده فقط عکس موردنظرش رو در اختیار برنامه بذاره، بدون اینکه اپلیکیشن دسترسی گسترده‌ای به کل گالری بخواد. قرارداد PickVisualMedia یک عکس یا ویدئو رو انتخاب می‌کنه و در صورت انتخاب موفق یک Uri برمی‌گردونه؛ در صورت انصراف کاربر هم مقدار null میده. این قرارداد در دستگاه‌هایی که Photo Picker اصلی رو ندارن، از مسیرهای جایگزین سیستم استفاده می‌کنه.

در Compose، بخش متمایز انتخاب عکس به این شکله:

val galleryLauncher = rememberLauncherForActivityResult(
    contract = ActivityResultContracts.PickVisualMedia()
) { uri ->
    uri?.let(viewModel::onImageSelected)
}

rememberLauncherForActivityResult یک Launcher می‌سازه که می‌تونه یک قابلیت خارج از Compose رو اجرا کنه و نتیجه رو برگردونه.

در اینجا قرارداد ما PickVisualMedia است. وقتی کاربر انتخابگر عکس رو می‌بنده، Callback اجرا میشه. اگه کاربر واقعاً عکسی انتخاب کرده باشه، uri مقدار داره و اون رو به ViewModel تحویل میدیم. اگه کاربر دکمه Back رو زده باشه، مقدار null میشه و کاری انجام نمیدیم.

برای باز کردن گالری، Launcher رو این‌طور اجرا می‌کنیم:

galleryLauncher.launch(
    PickVisualMediaRequest(
        ActivityResultContracts.PickVisualMedia.ImageOnly
    )
)

ImageOnly میگه فقط تصویرها نمایش داده بشن، نه ویدئوها. خود Photo Picker هم خروجی رو به شکل Uri برمی‌گردونه. Uri انتخاب‌شده معمولاً برای خواندن مناسبه، اما نباید فرض کنیم فایل اصلی قابل ویرایش یا نوشتنه.

صفحه در اینجا فقط میگه:

کاربر این عکس رو انتخاب کرده.

اینکه عکس باید برش بخوره، فشرده بشه یا آپلود بشه، وظیفه Launcher گالری نیست.

آیا برای گالری Permission لازم داریم؟

اگه از Photo Picker سیستم استفاده کنیم، برنامه برای انتخاب محدود عکس معمولاً نیازی به گرفتن دسترسی گسترده کل گالری نداره. کاربر خودش محتوای مشخصی رو انتخاب می‌کنه و سیستم فقط دسترسی لازم به همون مورد رو در اختیار برنامه قرار میده. این یکی از دلایلیه که Photo Picker نسبت به درخواست مستقیم دسترسی کامل تصاویر، انتخاب بهتریه.

بنابراین نباید از روی عادت، همان ابتدای اجرای برنامه مجوز دسترسی تمام عکس‌ها رو درخواست کنیم. مجوز باید فقط وقتی گرفته بشه که واقعاً به اون سطح از دسترسی نیاز داریم.

برای قیمت‌بان که کاربر فقط قراره لوگو یا تصویر کسب‌وکار رو انتخاب کنه، Photo Picker کاملاً متناسب با نیاز ماست.

گرفتن عکس با دوربین

برای عکس دوربین می‌تونیم از قرارداد TakePicture استفاده کنیم:

val cameraLauncher = rememberLauncherForActivityResult(
    contract = ActivityResultContracts.TakePicture()
) { success ->
    if (success) {
        viewModel.onImageSelected(cameraImageUri)
    }
}

TakePicture خودش فایل نهایی رو به ما برنمی‌گردونه. قبل از باز کردن دوربین، باید یک Uri در اختیارش بذاریم. برنامه دوربین عکس گرفته‌شده رو داخل همون Uri ذخیره می‌کنه و در پایان فقط یک مقدار Boolean برمی‌گردونه که مشخص می‌کنه ذخیره تصویر موفق بوده یا نه.

برای باز کردن دوربین می‌نویسیم:

cameraLauncher.launch(cameraImageUri)

پس تفاوت دوربین و گالری اینه:

Gallery:
سیستم بعد از انتخاب، Uri رو به ما میده.

Camera:
ما قبل از باز کردن دوربین، Uri رو به سیستم میدیم.

علت این رفتار اینه که تصویر کامل دوربین ممکنه بزرگ باشه. بهتره دوربین اون رو مستقیم در یک فایل ذخیره کنه، نه اینکه یک Bitmap بزرگ رو داخل نتیجه Activity برگردونه.

قرارداد TakePicturePreview هم وجود داره، اما فقط یک تصویر کوچک پیش‌نمایش رو به شکل Bitmap برمی‌گردونه و برای عکسی که قراره برش بخوره و با کیفیت مناسب آپلود بشه، انتخاب اصلی ما نیست.

Uri دوربین رو چطور می‌سازیم؟

برنامه دوربین یک اپلیکیشن جدا از قیمت‌بانه. بنابراین نمی‌تونیم یک مسیر خصوصی معمولی از فایل‌های برنامه رو مستقیم به اون تحویل بدیم. برای اشتراک امن فایل بین برنامه خودمون و دوربین، از FileProvider استفاده می‌کنیم.

ابتدا یک فایل موقت می‌سازیم:

val imageFile = File.createTempFile(
    "business_photo_",
    ".jpg",
    context.cacheDir
)

این فایل داخل Cache برنامه ساخته میشه. موقتی بودنش مهمه، چون هنوز تصویر نهایی و تأییدشده کاربر نیست.

بعد با FileProvider یک Uri امن برای اون می‌سازیم:

val cameraImageUri = FileProvider.getUriForFile(
    context,
    "${context.packageName}.fileprovider",
    imageFile
)

FileProvider به جای یک آدرس ناامن file://، یک content:// Uri ایجاد می‌کنه و میشه دسترسی موقت لازم رو به برنامه دوربین داد. اندروید استفاده از Content URI و مجوزهای موقت رو برای اشتراک امن فایل بین برنامه‌ها در نظر گرفته است.

خود Provider باید در Manifest معرفی بشه:

<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
</provider>

exported="false" یعنی Provider به‌صورت عمومی در اختیار همه برنامه‌ها قرار نمی‌گیره. grantUriPermissions="true" اجازه میده دسترسی موقتی به Uri مشخص‌شده صادر بشه.

در تنظیمات FileProvider هم فقط پوشه محدودی رو که برای عکس‌ها نیاز داریم معرفی می‌کنیم. نباید ریشه حافظه یا تمام پوشه‌های برنامه رو به اشتراک بذاریم، چون محدوده‌های بیش از حد وسیع ممکنه فایل‌های حساس رو ناخواسته در معرض دسترسی قرار بدن.

مجوز دوربین

برای باز کردن دوربین معمولاً باید مجوز CAMERA در Manifest تعریف بشه:

<uses-permission android:name="android.permission.CAMERA" />

اما وجود این خط به تنهایی کافی نیست. اگه مجوز از نوع Runtime Permission باشه، باید هنگام نیاز از کاربر درخواست بشه.

قاعده تجربه کاربری اینه که نباید همان لحظه ورود به برنامه، بدون توضیح مجوز دوربین بخوایم. کاربر ابتدا روی گرفتن عکس می‌زنه و بعد برنامه مجوز رو درخواست می‌کنه. در این حالت، کاربر می‌فهمه مجوز دقیقاً برای چه کاری لازمه.

بخش متمایز درخواست Permission می‌تونه چنین باشه:

val cameraPermissionLauncher =
    rememberLauncherForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        if (granted) {
            cameraLauncher.launch(cameraImageUri)
        }
    }

اگه مجوز صادر بشه، دوربین باز میشه. اگه رد بشه، برنامه باید پیام قابل فهمی نمایش بده و همچنان گزینه گالری رو در اختیار کاربر بذاره.

هر دو مسیر باید به یک تابع برسن

بعد از انتخاب از گالری یا گرفتن عکس با دوربین، نباید دو فرایند جدا برای ادامه کار بسازیم. هر دو Uri رو به یک تابع می‌فرستیم:

fun onImageSelected(uri: Uri) {
    _uiState.update {
        it.copy(sourceImageUri = uri)
    }

    startCrop(uri)
}

این تابع Uri اولیه رو نگه می‌داره و فرایند Crop رو شروع می‌کنه.

از این لحظه دیگه مهم نیست تصویر از کجا اومده. بخش‌های بعدی فقط با یک تصویر ورودی کار دارن.

همین اصل در بسیاری از فرایندهای برنامه‌نویسی مفیده:

مسیرهای مختلف ورودی رو هرچه زودتر به یک مدل مشترک تبدیل کن.

چرا عکس رو Crop می‌کنیم؟

فرض کن کاربر از نمای کامل فروشگاه عکس گرفته، اما جای نمایش عکس در پنل یک مربع کوچکه. اگه تصویر کامل رو مستقیم داخل اون قرار بدیم، ممکنه بخش اصلی عکس دیده نشه یا تصویر به شکل نامناسب بریده بشه.

Crop به کاربر اجازه میده محدوده مهم عکس رو مشخص کنه. مثلاً برای لوگوی کسب‌وکار می‌تونیم نسبت ثابت مربع داشته باشیم:

1 : 1

برای تصویر کاور ممکنه نسبت دیگری نیاز داشته باشیم:

16 : 9

نسبت Crop باید از محل استفاده تصویر بیاد، نه از سلیقه توسعه‌دهنده. اگه عکس در UI به شکل دایره نمایش داده میشه، باز هم معمولاً خروجی Crop رو مربع نگه می‌داریم و فقط هنگام نمایش اون رو دایره‌ای می‌کنیم.

فایل واقعی دایره‌ای نیست. دایره فقط شکل نمایش UIه.

Crop جزو کد داخلی اندروید نیست

اندروید یک جریان عمومی و یکپارچه برای انتخاب عکس داره، اما یک ابزار رسمی واحد که روی همه دستگاه‌ها رابط Crop کامل و یکسانی بده، وجود نداره. بنابراین در پروژه واقعی معمولاً یکی از این دو کار رو انجام میدیم:

استفاده از یک کتابخانه Crop معتبر

یا

ساخت صفحه Crop اختصاصی

در جزوه لازم نیست صدها خط مربوط به رابط Crop رو بنویسیم، چون هدف ما ساخت الگوریتم برش تصویر نیست. چیزی که مهمه، قرارداد بین صفحه ما و ابزار Crop است:

cropLauncher.launch(
    CropInput(
        sourceUri = sourceUri,
        aspectRatioX = 1f,
        aspectRatioY = 1f
    )
)

این کد نمونه مفهومی است. میگه ابزار Crop باید Uri اولیه و نسبت موردنیاز رو دریافت کنه.

بعد از پایان Crop، یک Uri یا File جدید تحویل می‌گیریم:

fun onCropFinished(croppedUri: Uri) {
    _uiState.update {
        it.copy(croppedImageUri = croppedUri)
    }
}

این خروجی دیگه عکس اصلی نیست. یک نسخه جدید از محدوده‌ایه که کاربر انتخاب کرده.

چرا نباید عکس اصلی کاربر رو تغییر بدیم؟

وقتی عکس از گالری انتخاب میشه، نباید تلاش کنیم همون فایل اصلی رو Crop یا بازنویسی کنیم. اولاً Uri انتخاب‌شده ممکنه قابل نوشتن نباشه. دوماً تغییر دادن فایل اصلی گالری رفتار خطرناکیه؛ کاربر فقط خواسته یک نسخه از عکس رو داخل قیمت‌بان استفاده کنه، نه اینکه تصویر شخصی خودش تغییر کنه.

پس Crop باید همیشه خروجی جدا بسازه:

Original Uri
     ↓
Crop
     ↓
New Temporary File

فایل اصلی فقط خوانده میشه. تمام تغییرات روی یک فایل موقت متعلق به برنامه انجام میشن.

Crop و Compress دو کار متفاوتن

گاهی Crop و Compress با هم اشتباه گرفته میشن، اما هدف اون‌ها فرق داره.

Crop بخشی از تصویر رو حذف می‌کنه:

عکس کامل فروشگاه
        ↓
فقط لوگو یا محدوده اصلی

Compress حجم فایل رو کم می‌کنه:

فایل ۶ مگابایتی
        ↓
فایل ۳۰۰ کیلوبایتی

Resize هم ابعاد پیکسلی رو کاهش میده:

4000 × 4000
      ↓
1080 × 1080

یک فرایند حرفه‌ای معمولاً هر سه مرحله رو در نظر می‌گیره:

Crop → Resize → Compress

اگه فقط Compress کنیم اما ابعاد تصویر همچنان ۶۰۰۰ پیکسل باشه، ممکنه فایل هنوز بیش از حد بزرگ بمونه و پردازش حافظه هم سنگین باشه.

چرا قبل از Upload عکس رو کوچک می‌کنیم؟

دوربین‌های جدید می‌تونن عکس‌هایی با ابعاد و حجم بسیار بالا تولید کنن. اما تصویر پروفایل قیمت‌بان شاید نهایتاً در یک محدوده چندصد پیکسلی نمایش داده بشه. ارسال عکس ۸ مگابایتی برای چنین استفاده‌ای فقط زمان و اینترنت کاربر رو هدر میده.

فشرده‌سازی قبل از Upload چند فایده داره:

مصرف کمتر اینترنت
آپلود سریع‌تر
فشار کمتر روی سرور
فضای ذخیره‌سازی کمتر
نمایش سریع‌تر عکس در دفعات بعد

اما نباید صرفاً کیفیت رو تا حد زیادی پایین بیاریم. هدف Compress نابود کردن عکس نیست؛ هدف پیدا کردن تعادل بین کیفیت بصری و حجم فایله.

برای یک لوگو یا تصویر پروفایل، می‌تونیم مثلاً خروجی‌ای با ضلع حداکثر ۱۰۸۰ پیکسل بسازیم. عدد دقیق باید براساس محل نمایش و سیاست Backend تعیین بشه.

خواندن تصویر از Uri

برای پردازش عکس، باید محتوای Uri رو بخونیم. نکته اصلی اینه که این کار از طریق ContentResolver انجام میشه:

val inputStream =
    context.contentResolver.openInputStream(uri)

openInputStream یک جریان خواندن از محتوا میده. از اینجا می‌تونیم تصویر رو Decode کنیم یا محتوای اون رو داخل فایل موقت کپی کنیم.

نباید فرض کنیم هر Uri یک File مستقیمه. بنابراین کدی مثل این در همه شرایط قابل اعتماد نیست:

File(uri.path!!)

uri.path ممکنه فقط بخشی از شناسه داخلی Content Provider باشه، نه مسیر واقعی روی حافظه.

Resize باید قبل از نگه داشتن Bitmap عظیم انجام بشه

اگه یک تصویر ۸۰۰۰ در ۸۰۰۰ رو با اندازه کامل داخل حافظه Decode کنیم، حتی اگه فایل فشرده فقط چند مگابایت باشه، Bitmap بازشده می‌تونه حافظه بسیار بیشتری مصرف کنه.

به همین دلیل، پردازشگر تصویر باید ابتدا ابعاد عکس رو بررسی کنه و بعد نسخه کوچک‌تری رو Decode کنه. لازم نیست جزئیات کامل الگوریتم رو اینجا بنویسیم، اما قرارداد مناسب می‌تونه چنین باشه:

val resizedBitmap = imageProcessor.decodeAndResize(
    uri = croppedUri,
    maxWidth = 1080,
    maxHeight = 1080
)

decodeAndResize یک تابع فرضی از کلاس ImageProcessor است. وظیفه اون اینه که بدون نگه داشتن بی‌دلیل نسخه غول‌پیکر، Bitmap متناسب با نیاز Upload بسازه.

این پردازش نباید روی Thread اصلی انجام بشه، چون Decode و Compress ممکنه زمان‌بر باشن. مستندات Android هم اشاره می‌کنن که Bitmap.compress() ممکنه چند ثانیه طول بکشه و باید خارج از Thread اصلی اجرا بشه.

فشرده‌سازی تصویر

بعد از Resize، تصویر رو داخل یک فایل موقت فشرده ذخیره می‌کنیم:

outputFile.outputStream().use { stream ->
    resizedBitmap.compress(
        Bitmap.CompressFormat.JPEG,
        82,
        stream
    )
}

Bitmap.CompressFormat.JPEG فرمت خروجی رو مشخص می‌کنه. عدد 82 کیفیت تقریبی JPEG است. در JPEG، مقدار کمتر معمولاً فایل کوچک‌تری می‌سازه و مقدار نزدیک ۱۰۰ کیفیت بیشتری حفظ می‌کنه. مقدار کیفیت باید با آزمایش واقعی روی عکس‌های پروژه انتخاب بشه، نه براساس یک عدد جادویی ثابت.

استفاده از use باعث میشه OutputStream بعد از پایان کار، حتی در صورت رخ دادن خطا، بسته بشه.

برای عکس‌های معمولی فروشگاه، JPEG می‌تونه مناسب باشه. اما اگه لوگو پس‌زمینه شفاف داشته باشه، JPEG شفافیت رو نگه نمی‌داره. در چنین حالتی PNG یا WebP مناسب‌تره. Android برای WebP حالت‌های Lossy و Lossless جداگانه داره و حالت قدیمی عمومی WEBP از API 30 به بعد به نفع نسخه‌های روشن‌تر کنار گذاشته شده است.

پس انتخاب فرمت باید به نوع تصویر وابسته باشه:

عکس واقعی فروشگاه → JPEG یا WebP Lossy

لوگوی دارای شفافیت → PNG یا WebP Lossless

کیفیت و ابعاد رو Backend هم باید کنترل کنه

فشرده‌سازی داخل اپلیکیشن تجربه کاربر رو بهتر می‌کنه، اما سرور نباید کورکورانه به فایل ارسالی اعتماد کنه.

Backend باید دوباره بررسی کنه:

فایل واقعاً تصویر باشه
فرمت مجاز باشه
حجم از حد مشخص بیشتر نباشه
ابعاد غیرعادی نباشن
فایل خراب یا مخرب نباشه

محدود کردن فایل در اندروید برای سرعت و تجربه کاربریه. کنترل نهایی سمت سرور برای امنیت و حفظ سلامت سیستم انجام میشه.

همون اصلی که در اعتبارسنجی فرم داشتیم، اینجا هم تکرار میشه:

اپلیکیشن قبل از ارسال بررسی می‌کنه؛ سرور قبل از اعتماد دوباره بررسی می‌کنه.

State فرایند عکس

آپلود عکس فقط Loading و Success نیست. کاربر ممکنه هنوز عکسی انتخاب نکرده باشه، در حال Crop باشه، فایل در حال پردازش باشه یا Upload در حال اجرا باشه.

یک State مناسب می‌تونه این شکل رو داشته باشه:

data class BusinessImageUiState(
    val previewUri: Uri? = null,
    val isProcessing: Boolean = false,
    val uploadProgress: Int? = null,
    val isUploaded: Boolean = false,
    val errorMessage: String? = null
)

previewUri تصویریه که باید قبل از Upload به کاربر نمایش داده بشه. isProcessing برای Crop، Resize یا Compress استفاده میشه. uploadProgress درصد پیشرفت Upload رو نگه می‌داره. isUploaded یعنی نسخه جدید روی سرور ذخیره شده و errorMessage هم خطای فعلی رو نمایش میده.

اینجا یک data class از چند State جدا مناسب‌تره، چون ممکنه هم‌زمان پیش‌نمایش تصویر وجود داشته باشه و Upload هم در حال انجام باشه.

مثلاً:

previewUri ≠ null
isProcessing = false
uploadProgress = 45

یعنی تصویر آماده و قابل نمایش است و در حال حاضر ۴۵ درصد فایل آپلود شده.

پردازش عکس در ViewModel یا Repository؟

ViewModel نباید خودش با Bitmap، InputStream و فایل موقت کار کنه. بهتره یک کلاس مخصوص پردازش تصویر داشته باشیم:

interface ImageProcessor {
    suspend fun prepareForUpload(uri: Uri): File
}

این Interface میگه هر پردازشگری که پیاده‌سازی بشه، یک Uri می‌گیره و در نهایت یک File آماده Upload برمی‌گردونه.

جزئیات داخل پیاده‌سازی پنهان میشن:

خواندن Uri
اصلاح جهت تصویر
Resize
Compress
ساخت فایل موقت

ViewModel فقط این کار رو انجام میده:

val uploadFile =
    imageProcessor.prepareForUpload(croppedUri)

این جداسازی چند مزیت داره. ViewModel ساده‌تر می‌مونه، پردازش تصویر مستقل تست میشه و اگه بعداً فرمت یا اندازه خروجی تغییر کرد، مجبور نیستیم منطق صفحه رو دست‌کاری کنیم.

چرا جهت عکس ممکنه اشتباه باشه؟

بعضی دوربین‌ها تصویر رو همیشه با پیکسل‌های چرخیده ذخیره نمی‌کنن. به جای اون، اطلاعات جهت عکس رو در Metadata قرار میدن. اگه پردازشگر این Metadata رو نادیده بگیره، ممکنه تصویری که در گالری درست دیده میشه، بعد از Decode یا Upload چرخیده نمایش داده بشه.

بنابراین ImageProcessor باید جهت تصویر رو هم بررسی کنه:

val correctedBitmap =
    imageOrientation.correct(bitmap, uri)

این کد مفهومی است و میگه قبل از Crop نهایی یا Compress باید جهت واقعی تصویر اعمال بشه.

مشکل جهت تصویر معمولاً زمانی دیده میشه که برنامه روی گوشی‌های مختلف آزمایش بشه. ممکنه روی دستگاه توسعه‌دهنده همه‌چیز درست باشه، اما روی برند دیگری عکس ۹۰ درجه چرخیده ذخیره بشه.

ساخت درخواست Upload

برخلاف فرم متنی، فایل تصویر معمولاً داخل JSON معمولی ارسال نمیشه. برای ارسال فایل همراه درخواست HTTP از multipart/form-data استفاده می‌کنیم.

در Retrofit بخش متمایز Endpoint به این شکله:

@Multipart
@POST("business/profile/image")
suspend fun uploadBusinessImage(
    @Part image: MultipartBody.Part
): UploadImageResponse

@Multipart میگه بدنه درخواست از چند بخش تشکیل میشه. حتی اگه فعلاً فقط یک فایل داشته باشیم، هر فایل یا فیلد متنی می‌تونه یک Part جدا باشه.

@Part image فایل تصویر رو داخل یکی از همین بخش‌ها قرار میده.

Multipart برای ارسال فایل و فیلدهای همراه اون طراحی شده و OkHttp ساختار MultipartBody و MultipartBody.Part رو برای همین نوع درخواست فراهم می‌کنه. (Square Open Source)

تبدیل File به Multipart

فایل فشرده‌شده باید به RequestBody تبدیل بشه:

val requestBody = file.asRequestBody(
    "image/jpeg".toMediaType()
)

image/jpeg نوع محتوای فایل رو مشخص می‌کنه. سرور با استفاده از MIME Type متوجه میشه این بخش از درخواست چه نوع داده‌ایه.

بعد اون رو داخل Multipart قرار میدیم:

val imagePart = MultipartBody.Part.createFormData(
    name = "image",
    filename = file.name,
    body = requestBody
)

name = "image" باید با نامی که Backend انتظار داره هماهنگ باشه.

filename نام فایل ارسالیه و body محتوای واقعی اون رو نگه می‌داره.

حالا Repository می‌تونه فایل رو ارسال کنه:

val response = api.uploadBusinessImage(imagePart)

پاسخ Upload نباید فقط موفق بود باشه

بعد از Upload، سرور بهتره اطلاعات نسخه ذخیره‌شده رو برگردونه:

data class UploadImageResponse(
    val imageUrl: String,
    val updatedAt: String
)

imageUrl آدرسیه که از این به بعد برای نمایش عکس استفاده میشه. updatedAt هم می‌تونه برای تشخیص نسخه جدید یا مدیریت Cache کاربرد داشته باشه.

Repository بعد از دریافت پاسخ، اطلاعات کسب‌وکار داخل Room رو به‌روزرسانی می‌کنه:

businessDao.updateImageUrl(
    imageUrl = response.imageUrl
)

با این کار، تمام صفحه‌هایی که اطلاعات کسب‌وکار رو مشاهده می‌کنن، آدرس جدید رو دریافت می‌کنن.

مسیر نهایی دوباره به الگوی Offline First برمی‌گرده:

Upload API
     ↓
Image URL
     ↓
Room
     ↓
Flow
     ↓
Dashboard و Profile

صفحه نباید بعد از Upload، تصویر تمام بخش‌های برنامه رو دستی عوض کنه. فقط منبع اصلی داده به‌روزرسانی میشه و بقیه UI به اون واکنش نشون میدن.

نمایش عکس قبل از Upload

بهتره کاربر قبل از ارسال، نتیجه Crop رو ببینه:

AsyncImage(
    model = uiState.previewUri,
    contentDescription = "تصویر کسب‌وکار"
)

این پیش‌نمایش از Uri محلی میاد، نه از سرور. بنابراین بلافاصله بعد از Crop قابل نمایش است.

این رفتار دو فایده داره. اول اینکه کاربر مطمئن میشه محدوده عکس رو درست انتخاب کرده. دوم اینکه برنامه حتی قبل از پایان Upload، بازخورد بصری مناسبی میده.

اما باید تفاوت پیش‌نمایش و عکس ذخیره‌شده رو روشن نگه داریم:

Preview:
فایل محلی و هنوز ذخیره‌نشده

Uploaded Image:
نسخه تأییدشده روی سرور

اگه Upload شکست بخوره، نباید برنامه طوری رفتار کنه که انگار عکس واقعاً تغییر کرده.

آپلود خودکار یا دکمه جدا؟

بعد از Crop دو انتخاب داریم.

در روش اول، Upload فوراً شروع میشه:

Select → Crop → Compress → Upload

در روش دوم، ابتدا پیش‌نمایش نمایش داده میشه و کاربر روی ذخیره عکس می‌زنه:

Select → Crop → Preview → Save → Upload

برای عکس پروفایل کسب‌وکار، روش دوم معمولاً کنترل بیشتری به کاربر میده. ممکنه بعد از Crop متوجه بشه تصویر مناسب نیست و بخواد عکس دیگری انتخاب کنه.

بخش متمایز دکمه ذخیره ساده است:

Button(
    enabled = uiState.previewUri != null &&
        !uiState.isProcessing,
    onClick = viewModel::uploadImage
)

دکمه فقط وقتی فعال میشه که تصویر آماده وجود داشته باشه و پردازش دیگری در حال اجرا نباشه.

عملیات کامل داخل ViewModel

ViewModel ابتدا تصویر رو پردازش می‌کنه:

fun prepareImage(uri: Uri) {
    viewModelScope.launch {
        _uiState.update {
            it.copy(
                isProcessing = true,
                errorMessage = null
            )
        }

        try {
            val file = imageProcessor.prepareForUpload(uri)
            preparedFile = file

            _uiState.update {
                it.copy(
                    previewUri = file.toUri(),
                    isProcessing = false
                )
            }
        } catch (error: Exception) {
            showImageError(error)
        }
    }
}

در آغاز، isProcessing روی true قرار می‌گیره تا صفحه Loading مناسب نمایش بده.

prepareForUpload کارهای سنگین رو انجام میده و یک فایل نهایی می‌سازه. فایل در ViewModel یا یک Holder موقت نگه داشته میشه تا وقتی کاربر دکمه ذخیره رو زد، همون نسخه ارسال بشه.

اگه پردازش موفق باشه، Uri فایل آماده داخل State قرار می‌گیره تا Preview نمایش داده بشه.

اگه خطایی رخ بده، نباید برنامه Crash کنه. ممکنه فایل انتخاب‌شده خراب، فرمتش نامعتبر یا حافظه گوشی ناکافی باشه.

Upload در Repository

Repository فایل آماده رو دریافت می‌کنه:

suspend fun uploadBusinessImage(file: File) {
    val response = api.uploadBusinessImage(
        file.toMultipartPart("image")
    )

    businessDao.updateImageUrl(response.imageUrl)
}

تابع toMultipartPart جزئیات ساخت RequestBody رو پنهان می‌کنه.

Repository دو مسئولیت مرتبط با داده رو هماهنگ می‌کنه: فایل رو به API می‌فرسته و بعد نتیجه تأییدشده رو داخل Room ذخیره می‌کنه.

در ViewModel فقط نتیجه مهمه:

viewModelScope.launch {
    try {
        repository.uploadBusinessImage(preparedFile)
        onUploadSuccess()
    } catch (error: Exception) {
        onUploadError(error)
    }
}

نمایش درصد Upload

برای فایل‌های کوچک ممکنه یک Loading ساده کافی باشه. اما اگه عکس‌ها بزرگ‌تر باشن یا سرعت اینترنت پایین باشه، نمایش درصد پیشرفت تجربه بهتری ایجاد می‌کنه:

در حال آپلود: ۴۷٪

برای این کار، RequestBody سفارشی می‌تونه تعداد بایت‌های ارسال‌شده رو گزارش کنه:

repository.uploadBusinessImage(file) { progress ->
    _uiState.update {
        it.copy(uploadProgress = progress)
    }
}

این کد میگه Repository هنگام ارسال فایل، درصد پیشرفت رو به ViewModel اعلام کنه.

اما برای نسخه اولیه قیمت‌بان، اگه فایل قبل از Upload به چندصد کیلوبایت کاهش پیدا می‌کنه، نمایش یک CircularProgressIndicator ممکنه کافی باشه. نباید فقط برای نمایش درصد، پیچیدگی زیادی وارد پروژه کنیم؛ مگر اینکه آپلود واقعاً زمان قابل توجهی بگیره.

جلوگیری از چند Upload هم‌زمان

هنگام Upload، دکمه ذخیره باید غیرفعال بشه:

enabled = uiState.uploadProgress == null

یا در State یک مقدار روشن‌تر داشته باشیم:

val isUploading: Boolean

بعد:

enabled = !uiState.isUploading

این شرط جلوی ارسال چند نسخه یکسان و ایجاد درخواست‌های هم‌زمان رو می‌گیره.

خود ViewModel هم بهتره محافظ داخلی داشته باشه:

if (_uiState.value.isUploading) return

غیرفعال کردن دکمه رفتار UI رو اصلاح می‌کنه، اما شرط ViewModel جلوی اجرای دوباره عملیات از هر مسیر دیگری رو هم می‌گیره.

خطاهای احتمالی این فرایند

آپلود عکس می‌تونه در مراحل مختلف شکست بخوره:

دوربین باز نشد
مجوز دوربین رد شد
کاربر انتخاب عکس رو لغو کرد
فایل قابل خواندن نبود
فرمت پشتیبانی نشد
Crop شکست خورد
حافظه کافی نبود
فشرده‌سازی انجام نشد
اینترنت قطع شد
سرور فایل رو رد کرد
Upload نیمه‌کاره موند

این خطاها نباید همگی با پیام خطایی رخ داد نمایش داده بشن.

مثلاً:

امکان خواندن این تصویر وجود نداره.
یک عکس دیگه انتخاب کن.

یا:

آپلود انجام نشد.
اتصال اینترنت رو بررسی کن و دوباره تلاش کن.

اگه Upload شکست بخوره، فایل آماده و Preview باید حفظ بشن تا کاربر فقط دوباره روی تلاش مجدد بزنه.

نباید کاربر رو مجبور کنیم دوباره وارد گالری بشه، Crop رو تکرار کنه و از اول همه مراحل رو انجام بده.

Retry فقط مرحله شکست‌خورده رو تکرار می‌کنه

فرض کن انتخاب، Crop و Compress موفق بودن اما Upload به دلیل قطع اینترنت شکست خورده. در این حالت Retry نباید کل فرایند رو از ابتدا اجرا کنه.

مسیر درست اینه:

preparedFile موجود است
        ↓
Retry
        ↓
فقط Upload دوباره اجرا میشه

پس ViewModel باید تا زمان خروج کاربر یا موفقیت Upload، فایل آماده رو نگه داره:

private var preparedFile: File? = null

تابع Retry هم فقط همون فایل رو می‌فرسته:

fun retryUpload() {
    preparedFile?.let(::uploadFile)
}

این نمونه‌ای از طراحی درست Recovery است. برنامه باید بدونه کدام مرحله موفق شده و از همان نقطه ادامه بده.

فایل‌های موقت رو فراموش نکن

در این فرایند ممکنه چند فایل موقت ساخته بشن:

فایل دوربین
فایل خروجی Crop
فایل Resize و Compress

اگه این فایل‌ها هیچ‌وقت پاک نشن، Cache برنامه به مرور بزرگ میشه.

بعد از Upload موفق می‌تونیم فایل‌های موقت رو حذف کنیم:

preparedFile?.delete()
preparedFile = null

اما باید مراقب باشیم قبل از پایان Upload یا وقتی هنوز Preview به فایل وابسته است، فایل رو پاک نکنیم.

همچنین اگه کاربر عکس جدیدی انتخاب کرد، نسخه آماده قبلی دیگه لازم نیست:

preparedFile?.delete()
preparedFile = null

مدیریت فایل‌های موقت بخشی از فرایند آپلود است، نه یک جزئیات بی‌اهمیت.

حذف عکس فعلی

اگه کاربر گزینه حذف عکس رو انتخاب کنه، نباید فقط تصویر رو از UI پنهان کنیم. سرور هم باید بدونه عکس حذف شده.

Endpoint می‌تونه چنین باشه:

@DELETE("business/profile/image")
suspend fun deleteBusinessImage()

بعد Repository مقدار محلی رو هم پاک می‌کنه:

api.deleteBusinessImage()
businessDao.updateImageUrl(null)

ترتیب اینجا مهمه. بهتره ابتدا سرور حذف رو تأیید کنه و بعد Room تغییر کنه. اگه حذف فقط در Room انجام بشه، عکس با Refresh بعدی دوباره برمی‌گرده.

مشکل Cache تصویر بعد از Upload

گاهی Upload موفق میشه، اما تصویر قبلی همچنان در UI دیده میشه. دلیلش ممکنه Cache کتابخانه نمایش عکس باشه.

فرض کن URL همیشه اینه:

https://api.example.com/business/image/15.jpg

فایل روی سرور عوض شده، اما URL همونه. کتابخانه نمایش تصویر ممکنه فکر کنه نسخه کش‌شده هنوز معتبره.

یکی از راه‌ها اینه که Backend برای هر نسخه URL تازه‌ای برگردونه:

/business/image/15_1723456.jpg

یا نسخه رو به Query اضافه کنیم:

/business/image/15.jpg?v=1723456

updatedAt پاسخ Upload می‌تونه برای همین کار استفاده بشه. این مسئله مربوط به خود Upload نیست، اما بدون حل اون ممکنه کاربر تصور کنه تغییر عکس انجام نشده.

آیا Upload باید آفلاین صف‌بندی بشه؟

از نظر فنی میشه فایل رو محلی نگه داشت و با WorkManager بعد از اتصال اینترنت آپلود کرد. این روش برای سیستم‌هایی که عکس‌های زیادی ثبت می‌کنن مفیده.

اما برای تغییر عکس پروفایل کسب‌وکار، نسخه ابتدایی می‌تونه رفتار ساده‌تری داشته باشه:

اینترنت نیست
      ↓
عکس آماده و Preview حفظ میشه
      ↓
کاربر بعداً Retry می‌کنه

صف‌بندی آفلاین فایل پیچیدگی‌هایی مثل نگهداری طولانی فایل، لغو Upload، تکرار درخواست و تشخیص نسخه جدیدتر ایجاد می‌کنه.

پس بهتره اول نیاز واقعی پروژه رو ببینیم. Offline First به این معنی نیست که تمام عملیات‌ها حتماً باید در پس‌زمینه صف‌بندی بشن. به این معنیه که برنامه هنگام نبود اینترنت داده و کار کاربر رو بی‌دلیل از بین نبره.

مسئولیت هر بخش

در این فرایند، تقسیم مسئولیت‌ها به این شکله:

Compose:
باز کردن Camera و Gallery
نمایش Preview و Loading
ارسال رویدادهای کاربر

ViewModel:
نگهداری State
هماهنگ کردن مراحل
مدیریت موفقیت، خطا و Retry

ImageProcessor:
خواندن Uri
اصلاح جهت
Resize
Compress
ساخت فایل نهایی

Repository:
ساخت درخواست Multipart
Upload به API
به‌روزرسانی Room

Backend:
اعتبارسنجی فایل
ذخیره تصویر
ساخت URL نهایی

اگه Compose خودش Bitmap رو فشرده کنه، Multipart بسازه و Room رو تغییر بده، خیلی سریع به صفحه‌ای شلوغ و غیرقابل نگهداری می‌رسیم.

در مقابل، اگه هر بخش فقط کار خودش رو انجام بده، میشه روش انتخاب عکس یا نوع فشرده‌سازی رو بدون بازنویسی کل صفحه تغییر داد.

آپلود عکس فقط ارسال فایل نیست

کاربر در ظاهر فقط روی یک تصویر می‌زنه، عکسی انتخاب می‌کنه و دکمه ذخیره رو فشار میده. اما پشت همین تعامل ساده، چند سیستم مختلف با هم همکاری می‌کنن.

Photo Picker یک Uri محدود و امن از گالری میده. دوربین تصویر رو داخل Uriای که برنامه از قبل ساخته ذخیره می‌کنه. Crop محدوده مناسب رو از تصویر جدا می‌کنه. ImageProcessor ابعاد و حجم فایل رو کاهش میده. Repository فایل رو به درخواست Multipart تبدیل می‌کنه. سرور نسخه نهایی رو ذخیره می‌کنه و URL جدید رو برمی‌گردونه. Room این URL رو نگه می‌داره و تمام صفحه‌های برنامه به‌صورت خودکار تصویر جدید رو دریافت می‌کنن.

مهم‌ترین نکته این درس اینه که عکس یک داده واحد نیست؛ یک فرایند چندمرحله‌ایه. باید بدونیم در هر مرحله چه نسخه‌ای از تصویر داریم:

عکس اولیه
عکس Crop‌شده
فایل فشرده‌شده
نسخه آپلودشده
آدرس ذخیره‌شده در Room

هر کدوم هدف متفاوتی دارن و نباید با هم اشتباه گرفته بشن.

در نهایت، مسیر آپلود عکس در قیمت‌بان رو میشه این‌طور خلاصه کرد:

برنامه عکس رو از دوربین یا گالری به شکل Uri دریافت می‌کنه، بدون تغییر فایل اصلی اون رو Crop و فشرده می‌کنه، نسخه آماده رو با Multipart برای سرور می‌فرسته و بعد از دریافت تأیید، آدرس عکس جدید رو داخل Room ذخیره می‌کنه تا تمام بخش‌های برنامه به‌صورت خودکار به‌روز بشن.

درس بیست‌وششم

برنامه چطور موقعیت واقعی کسب‌وکار رو از GPS می‌گیره یا روی نقشه از کاربر دریافت می‌کنه؟

انتخاب موقعیت روی نقشه

فرض کن صاحب یک سوپرمارکت یا رستوران در حال ثبت اطلاعات کسب‌وکارشه. نام فروشگاه، شماره تماس و عکس رو وارد کرده، اما هنوز یک سؤال مهم باقی مونده:

این فروشگاه دقیقاً کجاست؟

نوشتن آدرس به تنهایی همیشه کافی نیست. ممکنه کاربر آدرس رو اشتباه بنویسه، چند خیابون هم‌نام وجود داشته باشه یا حتی فرمت نوشتن آدرس‌ها متفاوت باشه. اما اگر مختصات دقیق جغرافیایی فروشگاه ثبت بشه، برنامه همیشه می‌دونه محل واقعی کسب‌وکار کجاست.

به همین دلیل تقریباً تمام اپلیکیشن‌های امروزی، علاوه بر آدرس متنی، مختصات GPS رو هم ذخیره می‌کنن.

در ظاهر کاربر فقط روی نقشه یک نقطه انتخاب می‌کنه، اما پشت صحنه چند سیستم مختلف با هم همکاری می‌کنن.

Permission
      ↓
Location Service
      ↓
GPS / Network
      ↓
Latitude + Longitude
      ↓
نمایش روی Map
      ↓
جابجایی Marker
      ↓
ذخیره مختصات
      ↓
API
      ↓
Room

این درس فقط درباره نمایش نقشه نیست. موضوع اصلی اینه که موقعیت جغرافیایی هم مثل عکس، یک فرایند چندمرحله‌ایه.

Location با GPS فرق داره

یکی از رایج‌ترین اشتباه‌ها اینه که Location و GPS رو یکی بدونیم.

GPS فقط یکی از روش‌های پیدا کردن موقعیته.

گوشی می‌تونه موقعیت رو از چند منبع مختلف به دست بیاره:

GPS

دکل‌های مخابراتی

Wi-Fi

Bluetooth

ترکیب همه این‌ها

بنابراین وقتی داخل اندروید می‌نویسیم:

Location

منظور موقعیت جغرافیایی است، نه الزاماً GPS.

سیستم خودش تصمیم می‌گیره از کدام منبع استفاده کنه تا سریع‌تر و دقیق‌تر موقعیت رو پیدا کنه.

Location یعنی چه چیزی؟

وقتی برنامه موقعیت رو دریافت می‌کنه، فقط یک نقطه روی نقشه نیست.

کلاس Location اطلاعات بیشتری داره.

مهم‌ترین بخش‌های اون عبارتند از:

Latitude

Longitude

Accuracy

Altitude

Speed

Bearing

Time

اما برای قیمت‌بان تقریباً فقط به دو مقدار نیاز داریم:

Latitude

Longitude

مثلاً:

Latitude:
35.6892

Longitude:
51.3890

این دو عدد محل دقیق فروشگاه روی کره زمین رو مشخص می‌کنن.

چرا آدرس کافی نیست؟

فرض کن کاربر نوشته:

تهران
خیابان آزادی
پلاک ۲۴۵

این آدرس برای انسان قابل فهمه.

اما برنامه نمی‌تونه فاصله دو فروشگاه رو فقط با متن محاسبه کنه.

اما اگر مختصات داشته باشیم:

35.700012

51.347814

برنامه می‌تونه:

• نزدیک‌ترین فروشگاه رو پیدا کنه.
• فاصله تا کاربر رو حساب کنه.
• مسیر روی نقشه رسم کنه.
• شعاع جستجو ایجاد کنه.
• فروشگاه‌های اطراف رو نمایش بده.

بنابراین Location زبان مشترک همه سیستم‌های نقشه است.

Permission

برنامه اجازه نداره بدون اطلاع کاربر موقعیت اون رو دریافت کنه.

قبل از هر چیز باید Permission گرفته بشه.

در Manifest فقط بخش متمایز اینه:

<uses-permission
    android:name="android.permission.ACCESS_FINE_LOCATION"/>

اگر دقت خیلی بالا لازم نباشه:

<uses-permission
    android:name="android.permission.ACCESS_COARSE_LOCATION"/>

Fine یا Coarse؟

فرق این دو خیلی مهمه.

ACCESS_FINE_LOCATION

≈ GPS
≈ چند متر دقت

اما

ACCESS_COARSE_LOCATION

≈ تقریبی

مثلاً چند صد متر

برای قیمت‌بان بهتره از موقعیت دقیق استفاده کنیم.

چون محل فروشگاه باید دقیق ثبت بشه.

درخواست Permission

در Compose مثل Camera از Activity Result API استفاده می‌کنیم.

بخش متمایز:

val permissionLauncher =
    rememberLauncherForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->

        if (granted) {
            viewModel.loadCurrentLocation()
        }

    }

این Launcher فقط یک سؤال از کاربر می‌پرسه:

اجازه میدی موقعیتت رو بخونم؟

اگر قبول کنه:

Location شروع میشه.

اگر رد کنه:

کاربر باید خودش نقطه رو روی نقشه انتخاب کنه.

اگر کاربر Permission نداد چه؟

برنامه نباید از کار بیفته.

همیشه باید مسیر جایگزین وجود داشته باشه.

مثلاً:

Permission رد شد

↓

نمایش نقشه

↓

کاربر خودش Marker رو جابه‌جا می‌کنه.

این یکی از اصول مهم طراحی حرفه‌ایه.

هیچ Permission نباید شرط استفاده از کل برنامه باشه.

دریافت موقعیت فعلی

امروزه تقریباً تمام برنامه‌ها از Fused Location Provider استفاده می‌کنن.

دلیلش اینه که خودش بهترین منبع موقعیت رو انتخاب می‌کنه.

مثلاً:

• اگر GPS روشن باشه از GPS.
• اگر داخل ساختمان باشیم از Wi-Fi.
• اگر GPS ضعیف باشه از شبکه موبایل.

بنابراین توسعه‌دهنده لازم نیست خودش تصمیم بگیره.

گرفتن آخرین موقعیت

بخش متمایز:

locationClient
    .lastLocation

این کد نمیگه:

GPS روشن کن.

بلکه میگه:

آخرین موقعیتی که سیستم می‌شناسه رو بده.

اگر وجود داشته باشه، خیلی سریع برمی‌گرده.

اگر آخرین موقعیت وجود نداشت؟

ممکنه گوشی تازه روشن شده باشه.

یا GPS هنوز هیچ موقعیتی پیدا نکرده باشه.

در این حالت باید موقعیت جدید درخواست کنیم.

مفهومی:

locationClient
    .getCurrentLocation(...)

این بار سیستم منتظر می‌مونه تا موقعیت واقعی پیدا بشه.

دریافت Location داخل ViewModel

ViewModel نباید خودش LocationManager بسازه.

بهتره Repository این کار رو انجام بده.

ViewModel

↓

LocationRepository

↓

Fused Location Provider

↓

Location

مثل همیشه ViewModel فقط نتیجه رو می‌گیره.

مدل موقعیت

بهتره مدل مستقلی داشته باشیم.

data class GeoPoint(

    val latitude: Double,

    val longitude: Double

)

چرا Location خود اندروید رو همه‌جا استفاده نکنیم؟

چون UI فقط مختصات لازم داره.

وابسته شدن کل برنامه به کلاس Location اندروید باعث میشه تست کردن و نگهداری سخت‌تر بشه.

نمایش نقشه

بعد از اینکه مختصات رو داریم، باید روی نقشه نمایش داده بشه.

Google Map

↓

Marker

↓

Latitude

Longitude

صفحه فقط مختصات رو به Map میده.

خود Map مسئول رسم Marker است.

State صفحه

data class MapUiState(

    val location: GeoPoint? = null,

    val isLoading: Boolean = false,

    val hasPermission: Boolean = false

)

این State تقریباً همه وضعیت‌های صفحه رو پوشش میده.

اگر Location وجود داشت

Map

↓

Move Camera

↓

Zoom

↓

Show Marker

کاربر مستقیم محل فروشگاه رو می‌بینه.

اگر Location وجود نداشت

مثلاً Permission رد شده.

یا GPS خاموشه.

در این حالت:

Map

↓

Default Location

↓

Marker قابل جابه‌جایی

مثلاً تهران رو نمایش می‌دیم تا کاربر خودش محل رو انتخاب کنه.

Marker

Marker همون سنجاق روی نقشه است.

وقتی کاربر اون رو جابه‌جا می‌کنه:

Marker

↓

Latitude

Longitude

↓

State

بخش متمایز:

viewModel.onMarkerMoved(
    latitude,
    longitude
)

داخل ViewModel:

_form.update {

    it.copy(

        location = GeoPoint(

            latitude,

            longitude

        )

    )

}

دقیقاً مثل TextField.

فقط این بار مقدار Text تغییر نکرده.

مختصات تغییر کرده.

چرا مختصات داخل فرم ذخیره میشه؟

چون ممکنه کاربر:

• چند بار Marker رو جابه‌جا کنه.
• بعد اسم فروشگاه رو تغییر بده.
• دوباره Marker رو جابه‌جا کنه.
• بعد ذخیره رو بزنه.

مختصات هم بخشی از فرم ویرایشه.

نه بخشی از خود Map.

ذخیره در سرور

مدل درخواست:

data class UpdateLocationRequest(

    val latitude: Double,

    val longitude: Double

)

Repository:

api.updateLocation(
    request
)

بعد از پاسخ موفق:

businessDao.updateLocation(
    latitude,
    longitude
)

مثل همیشه:

API

↓

Room

↓

Flow

↓

UI

نمایش آدرس

گاهی سرور فقط مختصات رو ذخیره می‌کنه.

اما کاربر دوست داره آدرس متنی هم ببینه.

برای این کار از Reverse Geocoding استفاده میشه.

Latitude

Longitude

↓

Address

مثلاً:

35.7001

51.3432

↓

تهران
خیابان آزادی

نکته مهم اینه که این آدرس فقط برای نمایش به کاربره.

اطلاعات اصلی همون مختصاته.

اگر GPS خاموش بود

برنامه نباید Crash کنه.

پیام مناسب:

برای دریافت موقعیت فعلی،
GPS رو روشن کن.

یا

محل رو روی نقشه انتخاب کن.

باز هم مسیر جایگزین وجود داره.

دقت Location

گاهی Location دقت کمی داره.

مثلاً:

Accuracy

=

350 متر

این یعنی گوشی مطمئن نیست.

اما اگر:

Accuracy

=

5 متر

موقعیت تقریباً دقیق محسوب میشه.

اگر دقت خیلی پایین بود، بهتره قبل از ذخیره از کاربر بخوایم Marker رو بررسی کنه.

آیا همیشه باید GPS بگیریم؟

نه.

فرض کن کاربر می‌خواد شعبه جدیدی در شهر دیگری ثبت کنه.

اگر فقط GPS داشته باشیم:

لوکیشن خود کاربر ثبت میشه.

نه فروشگاه.

در این حالت:

انتخاب دستی روی نقشه از GPS مهم‌تره.

بنابراین بهترین تجربه کاربری اینه:

ابتدا GPS
↓
نمایش Marker
↓
امکان جابه‌جایی دستی

این دقیقاً کاریه که بیشتر برنامه‌های حرفه‌ای انجام میدن.

مسئولیت هر بخش

Compose

نمایش نقشه

نمایش Marker

درخواست Permission

↓

ViewModel

مدیریت State

مختصات انتخاب‌شده

↓

LocationRepository
دریافت موقعیت
↓
API
ذخیره Location
↓
Room
نگهداری مختصات

مثل تمام درس‌های قبلی، هیچ بخشی نباید مسئولیت بخش دیگه رو انجام بده.

انتخاب موقعیت فقط نمایش نقشه نیست

وقتی کاربر روی نقشه یک نقطه انتخاب می‌کنه، در واقع چند سیستم مختلف با هم همکاری می‌کنن. برنامه ابتدا Permission لازم رو درخواست می‌کنه، در صورت امکان موقعیت فعلی رو از سرویس مکان‌یابی دریافت می‌کنه، اون رو روی نقشه نمایش میده و اجازه میده کاربر Marker رو جابه‌جا کنه. در نهایت مختصات انتخاب‌شده برای سرور ارسال میشن، داخل Room ذخیره میشن و تمام بخش‌های برنامه که از این اطلاعات استفاده می‌کنن به‌صورت خودکار به‌روز میشن.

مهم‌ترین نکته این درس اینه که نقشه فقط یک رابط کاربریه؛ چیزی که واقعاً ارزش ذخیره شدن داره، مختصات جغرافیاییه. نقشه، GPS و آدرس فقط ابزارهایی هستن که به کاربر کمک می‌کنن آن مختصات دقیق رو انتخاب کنه.

در نهایت، مسیر انتخاب موقعیت در قیمت‌بان رو میشه این‌طور خلاصه کرد: برنامه با گرفتن مجوز دسترسی، موقعیت فعلی یا انتخاب‌شده کاربر رو به مختصات جغرافیایی تبدیل می‌کنه، این مختصات رو داخل سرور و Room ذخیره می‌کنه و از اون به‌عنوان مرجع اصلی محل کسب‌وکار در تمام بخش‌های برنامه استفاده می‌کنه.

درس بیست‌وهفتم

برنامه چطور صدها دسته‌بندی مختلف رو از سرور دریافت می‌کنه، داخل گوشی ذخیره می‌کنه و سریع در اختیار کاربر قرار میده؟

مشاهده دسته‌بندی‌ها

تا اینجای کار، صاحب کسب‌وکار اطلاعات فروشگاهش رو ثبت کرده، عکس گذاشته و موقعیتش روی نقشه مشخص شده. اما هنوز یک بخش مهم باقی مونده؛ کالاها باید داخل دسته‌بندی مناسب قرار بگیرن.

فرض کن صاحب یک سوپرمارکت می‌خواد کالای نوشابه کوکاکولا رو اضافه کنه. قبل از اینکه نام کالا یا قیمت رو وارد کنه، باید مشخص بشه این کالا متعلق به کدوم دسته است:

نوشیدنی‌ها

لبنیات

مواد شوینده

تنقلات

مواد پروتئینی

...

در نگاه اول، شاید دسته‌بندی فقط یک لیست ساده از اسم‌ها به نظر برسه. اما در واقع، این لیست یکی از مهم‌ترین داده‌های مرجع (Reference Data) برنامه است؛ داده‌ای که تقریباً همه بخش‌های برنامه به اون وابسته هستن.

مسیر کلی دریافت دسته‌بندی‌ها به این شکله:

Server
↓
Category API
↓
Repository
↓
Room
↓
Flow
↓
Category ViewModel
↓
Compose List

این مسیر شاید شبیه درس‌های قبلی باشه، اما یک تفاوت مهم داره. دسته‌بندی‌ها اطلاعاتی نیستن که هر کاربر برای خودش داشته باشه. این داده‌ها معمولاً توسط مدیر سیستم تعریف میشن و بین همه کاربران مشترک هستن.

دسته‌بندی‌ها چرا داخل برنامه ثابت نیستن؟

شاید اولین ایده این باشه که بنویسیم:

val categories = listOf(

    "نوشیدنی",

    "لبنیات",

    "شوینده"

)

val categories = listOf(

    "نوشیدنی",

    "لبنیات",

    "شوینده"

)

برای یک پروژه کوچک شاید جواب بده.

اما فرض کن فردا مدیر سیستم تصمیم بگیره:

• دسته جدید اضافه کنه.
• نام یک دسته رو تغییر بده.
• ترتیب نمایش رو عوض کنه.
• بعضی دسته‌ها رو حذف کنه.

اگر لیست داخل کد برنامه باشه، برای هر تغییر باید نسخه جدید اپلیکیشن منتشر کنیم. به همین دلیل دسته‌بندی‌ها از سرور دریافت میشن.

مدل دسته‌بندی

هر دسته فقط یک اسم نیست. مثلاً:

data class Category(

    val id: Long,

    val name: String,

    val icon: String?,

    val parentId: Long?

)

data class Category(

    val id: Long,

    val name: String,

    val icon: String?,

    val parentId: Long?

)

هر فیلد دلیل خودش رو داره.

id
شناسه اصلی دسته است.

name
متنی که کاربر می‌بینه.

icon
ممکنه آدرس آیکون یا نام آن باشه.

parentId
برای دسته‌های تو در تو استفاده میشه.

مثلاً:

مواد غذایی
↓
نوشیدنی
↓
نوشابه

چرا id مهم‌تر از name است؟

فرض کن امروز سرور این اطلاعات رو داره:

id = 8

name = نوشیدنی

فردا مدیر سیستم تصمیم می‌گیره اسمش رو تغییر بده:

id = 8

name = نوشیدنی و آبمیوه

اگر کالاها بر اساس Name ذخیره شده باشن، همه ارتباط‌ها خراب میشه.

اما اگر فقط id ذخیره بشه:

CategoryId = 8

هر وقت اسم عوض بشه، برنامه خودکار اسم جدید رو نمایش میده.

بنابراین:

همیشه ارتباط بین داده‌ها با شناسه انجام میشه، نه متن قابل نمایش.

دریافت دسته‌بندی‌ها

Endpoint معمولاً چیزی شبیه اینه:

@GET("categories")
suspend fun getCategories(): List<CategoryDto>

@GET("categories")
suspend fun getCategories(): List<CategoryDto>

پاسخ سرور:

[
  {
    "id":1,
    "name":"نوشیدنی"
  },
  {
    "id":2,
    "name":"لبنیات"
  }
]

[
  {
    "id":1,
    "name":"نوشیدنی"
  },
  {
    "id":2,
    "name":"لبنیات"
  }
]

Repository پاسخ رو تبدیل می‌کنه:

response.map {

    it.toEntity()

}

response.map {

    it.toEntity()

}

و داخل Room ذخیره می‌کنه:

categoryDao.upsertAll(
    entities
)

categoryDao.upsertAll(
    entities
)

مثل همیشه:

API
↓
Room
↓
Flow
↓
UI

چرا Room؟

شاید بگی هر بار صفحه دسته‌بندی باز شد از API بخونیم. اما چند مشکل پیش میاد. اگر اینترنت نباشه هیچ دسته‌ای نداریم. اگر اینترنت کند باشه هر بار باید منتظر بمونیم. اگر چند صفحه از دسته‌بندی استفاده کنن هر صفحه دوباره درخواست میزنه. به همین دلیل دسته‌بندی‌ها هم داخل Room ذخیره میشن.

مشاهده دسته‌بندی‌ها

Repository:

fun observeCategories():

Flow<List<Category>>

fun observeCategories():

Flow<List<Category>>

این Flow همیشه آخرین نسخه دسته‌بندی‌ها رو منتشر می‌کنه.

اگر مدیر سیستم دسته جدید اضافه کنه و برنامه Sync انجام بده:
Room تغییر می‌کنه. Flow تغییر می‌کنه. UI تغییر می‌کنه. بدون حتی یک Refresh دستی.

ViewModel

مثل همیشه:

val categories =

repository
    .observeCategories()
    .stateIn(...)

val categories =

repository
    .observeCategories()
    .stateIn(...)

صفحه فقط همین State رو مشاهده می‌کنه.

State صفحه

data class CategoriesUiState(

    val categories:
        List<Category> = emptyList(),

    val isLoading:Boolean=false,

    val error:String?=null

)

data class CategoriesUiState(

    val categories:
        List<Category> = emptyList(),

    val isLoading:Boolean=false,

    val error:String?=null

)

دسته‌بندی‌ها فقط یکی از داده‌های صفحه هستن.

Loading و Error هم باید کنار اون وجود داشته باشن.

نمایش لیست

در Compose:

LazyColumn {

    items(

        state.categories

    ) { category ->

        CategoryItem(category)

    }

}

LazyColumn {

    items(

        state.categories

    ) { category ->

        CategoryItem(category)

    }

}

نکته مهم اینه که LazyColumn فقط آیتم‌هایی رو می‌سازه که روی صفحه دیده میشن.

اگر هزار دسته وجود داشته باشه، قرار نیست هزار Composable ساخته بشه.

همین دلیل استفاده از LazyColumn است.

چرا LazyColumn؟

فرض کن:
۲۰ دسته

فرقی نداره.

اما:
۲۰۰۰ دسته

اگر از Column معمولی استفاده کنیم:

۲۰۰۰ Composable ساخته میشه. مصرف حافظه بالا میره. اسکرول کند میشه. اما LazyColumn فقط بخش قابل مشاهده رو می‌سازه.

انتخاب دسته

وقتی کاربر روی یک دسته کلیک می‌کنه:

viewModel.onCategorySelected(
    category.id
)

viewModel.onCategorySelected(
    category.id
)

دقت کن. id ارسال میشه. نه Name. چون شناسه پایدار است.

داخل ViewModel:

_form.update {

    it.copy(

        categoryId = id

    )

}

_form.update {

    it.copy(

        categoryId = id

    )

}

دقیقاً مثل TextField. فقط این بار مقدار انتخاب‌شده یک شناسه است.

چرا فقط شناسه ذخیره میشه؟

فرض کن کالا:

کوکاکولا

اگر بنویسیم:

Category:

نوشیدنی

Category:

نوشیدنی

بعداً اگر اسم دسته تغییر کنه: تمام کالاها باید ویرایش بشن. اما اگر:

categoryId = 8

categoryId = 8

فقط جدول Category تغییر می‌کنه. تمام کالاها خودکار اسم جدید رو نمایش میدن.

جستجو داخل دسته‌ها

اگر دسته‌ها زیاد باشن: کاربر دوست نداره اسکرول کنه. بهتره Search داشته باشیم.

fun search(

    query:String

)

fun search(

    query:String

)

Repository:

categoryDao.search(query)

categoryDao.search(query)

به جای اینکه همه دسته‌ها داخل Compose فیلتر بشن.

چرا؟

اگر هزار دسته داشته باشیم: فیلتر داخل دیتابیس سریع‌تره. و فقط نتایج لازم برمی‌گردن.

مرتب‌سازی

ممکنه سرور ترتیب نمایش رو مشخص کنه.

مثلاً:

مواد غذایی نوشیدنی لبنیات …

در این حالت بهتره ترتیب رو هم از سرور بگیریم.

مثلاً:

val sortOrder:Int

val sortOrder:Int

بعد:

ORDER BY sortOrder

ORDER BY sortOrder

به جای مرتب کردن دستی داخل UI.

دسته‌های تو در تو

گاهی دسته‌بندی فقط یک سطح نیست.

مثلاً:

مواد غذایی
↓
نوشیدنی
↓
آبمیوه

اینجا:

parentId

همین مسئله رو حل می‌کنه.

اگر:

parentId = null

parentId = null

یعنی دسته اصلی.

اگر:

parentId = 5

parentId = 5

یعنی زیرمجموعه دسته شماره ۵.

گرفتن زیرمجموعه‌ها

Repository:

observeChildren(
    parentId
)

observeChildren(
    parentId
)

داخل DAO:

WHERE parentId = :parentId

WHERE parentId = :parentId

به جای اینکه کل درخت داخل Compose پردازش بشه.

Refresh

مثل Dashboard:

refreshCategories()

refreshCategories()

Repository:

API
↓
Room

نه:

API
↓
Compose

منبع اصلی همیشه Room باقی می‌مونه.

اگر اینترنت نبود

چون دسته‌ها داخل Room هستن:

کاربر همچنان می‌تونه دسته‌ها رو ببینه. حتی اگر اینترنت قطع باشه. فقط دسته‌های جدیدی که مدیر سیستم ساخته هنوز دریافت نشدن.

اگر هیچ دسته‌ای وجود نداشت

دو حالت وجود داره. اول:

Loading

هنوز اطلاعات نرسیده. دوم:

Empty

اطلاعات دریافت شده. اما واقعاً هیچ دسته‌ای وجود نداره. پیام مناسب:

هنوز هیچ دسته‌بندی‌ای تعریف نشده.
این با Error فرق داره.

انتخاب دسته نباید متن رو ذخیره کنه

گاهی افراد داخل فرم می‌نویسن:

selectedCategoryName

selectedCategoryName

و بعد همون رو داخل دیتابیس ذخیره می‌کنن.

این طراحی اشتباهه.

بهتره:

selectedCategoryId

selectedCategoryId

ذخیره بشه.

و هر زمان لازم بود:

Category Table
↓
Name

نمایش داده بشه.

مسئولیت هر بخش

Compose
نمایش لیست
کلیک روی آیتم
↓
ViewModel
مدیریت انتخاب
↓
Repository
Sync
↓
API
↓
Room

مثل همیشه UI نباید چیزی درباره Retrofit یا SQL بدونه.

دسته‌بندی‌ها فقط یک لیست ساده نیستن

در ظاهر، کاربر فقط چند اسم داخل یک لیست می‌بینه و روی یکی از اون‌ها کلیک می‌کنه. اما پشت همین تعامل ساده، یک معماری کامل وجود داره. Repository اطلاعات دسته‌بندی‌ها رو از سرور دریافت می‌کنه، داخل Room ذخیره می‌کنه و Flow آخرین نسخه رو در اختیار ViewModel قرار میده. صفحه فقط همین State رو مشاهده می‌کنه و شناسه دسته انتخاب‌شده رو به ViewModel برمی‌گردونه.

مهم‌ترین نکته این درس اینه که دسته‌بندی‌ها داده‌های مرجع برنامه هستن، نه داده‌های مخصوص یک کاربر. به همین دلیل باید یک‌بار از سرور دریافت بشن، داخل Room نگهداری بشن و همه بخش‌های برنامه از همان نسخه مشترک استفاده کنن.

در نهایت، مسیر مشاهده دسته‌بندی‌ها در قیمت‌بان رو میشه این‌طور خلاصه کرد:

برنامه فهرست دسته‌بندی‌ها رو از سرور دریافت و داخل Room ذخیره می‌کنه، رابط کاربری همیشه اطلاعات رو از Room می‌خونه و هنگام انتخاب، فقط شناسه دسته رو ذخیره می‌کنه تا تغییر نام یا ساختار دسته‌ها در آینده بدون تغییر اطلاعات کالاها مدیریت بشه.

درس بیست‌وهشتم

برنامه چطور هزاران محصول رو از سرور دریافت می‌کنه، داخل گوشی ذخیره می‌کنه و به سریع‌ترین شکل ممکن به کاربر نمایش میده؟

مشاهده محصولات

تا اینجای کار، صاحب کسب‌وکار فروشگاهش رو ساخته، اطلاعاتش رو ویرایش کرده، موقعیتش رو روی نقشه ثبت کرده و دسته‌بندی‌ها هم دریافت شدن. حالا مهم‌ترین بخش قیمت‌بان شروع میشه: لیست محصولات.

تقریباً تمام زمان کاربر داخل همین بخش می‌گذره. او هر روز محصولات رو جستجو می‌کنه، قیمت‌ها رو تغییر میده، کالاهای جدید اضافه می‌کنه و وضعیت کالاها رو بررسی می‌کنه. به همین دلیل، صفحه محصولات یکی از مهم‌ترین و حساس‌ترین صفحه‌های کل برنامه است. اگر این صفحه کند باشه، حتی اگر بقیه قسمت‌های برنامه عالی باشن، کاربر احساس می‌کنه کل اپلیکیشن کند و بی‌کیفیته.

در ظاهر فقط یک لیست از کالاها نمایش داده میشه، اما پشت همین صفحه چند سیستم مختلف با هم همکاری می‌کنن.

Server
↓
Products API
↓
Repository
↓
Room
↓
Flow
↓
ProductsViewModel
↓
Compose List

این معماری شبیه درس‌های قبلیه، اما این بار با یک تفاوت مهم روبه‌رو می‌شیم: تعداد داده‌ها خیلی بیشتره.

چرا صفحه محصولات با دسته‌بندی فرق داره؟

در درس قبل شاید فقط چند ده دسته‌بندی داشتیم.

مثلاً:

۴۰ دسته

اما محصولات ممکنه این تعداد باشن:

۳۰۰ کالا
۵۰۰۰ کالا
۵۰۰۰۰ کالا

بنابراین خیلی از روش‌هایی که برای لیست‌های کوچک مناسب بودن، اینجا دیگه جواب نمی‌دن.

مدل محصول

یک محصول فقط اسم نیست.

مثلاً:

data class Product(

    val id: Long,

    val name: String,

    val barcode: String?,

    val categoryId: Long,

    val imageUrl: String?,

    val lastPrice: Long?

)

data class Product(

    val id: Long,

    val name: String,

    val barcode: String?,

    val categoryId: Long,

    val imageUrl: String?,

    val lastPrice: Long?

)

هر کدوم از این فیلدها دلیل خودشون رو دارن.

id
شناسه محصول.

name
نام کالا.

barcode
بارکد.

categoryId
ارتباط با جدول دسته‌بندی.

imageUrl
تصویر کالا.

lastPrice
آخرین قیمت ثبت‌شده.

چرا قیمت داخل Product است؟

ممکنه بعداً قیمت‌ها تاریخچه داشته باشن. مثلاً:

امروز
دیروز
هفته قبل

در اون حالت شاید آخرین قیمت فقط برای نمایش سریع داخل Product نگهداری بشه و تاریخچه کامل داخل جدول دیگری ذخیره بشه. این یکی از مثال‌های خوب طراحی دیتابیسه.

دریافت محصولات

Endpoint:

@GET("products")
suspend fun getProducts(): List<ProductDto>

@GET("products")
suspend fun getProducts(): List<ProductDto>

پاسخ:

[
 {
   "id":1,
   "name":"کوکاکولا",
   "categoryId":8
 }
]

[
 {
   "id":1,
   "name":"کوکاکولا",
   "categoryId":8
 }
]

Repository:

val entities =
    response.map {

        it.toEntity()

    }

productDao.upsertAll(
    entities
)

val entities =
    response.map {

        it.toEntity()

    }

productDao.upsertAll(
    entities
)

مثل همیشه:

API
↓
Room
↓
Flow
↓
UI

چرا مستقیم از API نخونیم؟

فرض کن صفحه محصولات هر بار باز میشه. اگر مستقیم API بخونه:

باز شدن صفحه
↓
درخواست اینترنت
↓
انتظار

اگر اینترنت قطع باشه: هیچ محصولی نداریم. اگر کند باشه: صفحه دیر باز میشه. اما اگر Room منبع اصلی باشه:

باز شدن صفحه
↓
Room
↓
نمایش فوری

بعد در پس‌زمینه Sync انجام میشه.

مشاهده محصولات

Repository:

fun observeProducts():

Flow<List<Product>>

fun observeProducts():

Flow<List<Product>>

ViewModel:

val products =

repository
    .observeProducts()
    .stateIn(...)

val products =

repository
    .observeProducts()
    .stateIn(...)

صفحه فقط State رو مشاهده می‌کنه.

State صفحه

data class ProductsUiState(

    val products:
        List<Product> = emptyList(),

    val isLoading:Boolean=false,

    val isRefreshing:Boolean=false,

    val error:String?=null

)

data class ProductsUiState(

    val products:
        List<Product> = emptyList(),

    val isLoading:Boolean=false,

    val isRefreshing:Boolean=false,

    val error:String?=null

)

دقت کن. Loading و Refresh یکی نیستن.

Loading

اولین ورود
↓
هیچ داده‌ای نداریم

اما Refresh:

لیست وجود داره
↓
داده جدید در حال دریافت است

در Refresh نباید کل صفحه سفید بشه.

نمایش لیست

LazyColumn {

    items(

        state.products,

        key = { it.id }

    ) {

        ProductItem(it)

    }

}

LazyColumn {

    items(

        state.products,

        key = { it.id }

    ) {

        ProductItem(it)

    }

}

نکته مهم:

key = { it.id }

key = { it.id }

این یکی از مهم‌ترین بخش‌های LazyColumn است.

چرا key؟

فرض کن:

A
B
C

بعد محصول جدید بالای لیست اضافه بشه.

بدون key:
Compose ممکنه فکر کنه همه آیتم‌ها تغییر کردن.

اما با id:
می‌فهمه فقط یک آیتم جدید اضافه شده.

این باعث اسکرول روان‌تر و Recomposition کمتر میشه.

ProductItem

هر ردیف فقط مسئول نمایش یک محصوله. مثلاً:

ProductItem(

    product,

    onClick = {

        ...

    }

)

ProductItem(

    product,

    onClick = {

        ...

    }

)

داخل ProductItem نباید:

• Retrofit باشه.
• SQL باشه.
• ViewModel ساخته بشه.

فقط UI.

تصویر محصول

تصویر معمولاً از URL نمایش داده میشه.

مثلاً:

https://...

Compose:

AsyncImage(

    model = product.imageUrl,

    contentDescription = product.name

)

AsyncImage(

    model = product.imageUrl,

    contentDescription = product.name

)

AsyncImage خودش دانلود، Cache و نمایش تصویر رو مدیریت می‌کنه. ProductItem لازم نیست بدونه تصویر از اینترنت میاد.

اگر تصویر وجود نداشت

مثلاً:

imageUrl = null

imageUrl = null

در این حالت: Placeholder نمایش میدیم. نه اینکه Image خالی بمونه.

ارتباط محصول و دسته

داخل Product فقط:

categoryId

وجود داره. نه:

categoryName

چرا؟ چون دسته ممکنه تغییر کنه.

اگر بخوایم اسم دسته رو نمایش بدیم:

categoryId
↓
Category Table
↓
Category Name

آیا باید اسم دسته داخل Product ذخیره بشه؟

نه. این تکرار داده است. اگر:
لبنیات

بشه:
لبنیات و صبحانه

همه محصولات باید تغییر کنن. اما اگر فقط id داشته باشیم: فقط جدول Category تغییر می‌کنه.

مرتب‌سازی

کاربر معمولاً دوست داره:

الفبا آخرین ثبت پرفروش‌ترین …

ببینه.

این مرتب‌سازی بهتره داخل Repository انجام بشه.

نه داخل Compose.

مثلاً:

observeProductsOrderedByName()

observeProductsOrderedByName()

یا

ORDER BY name

ORDER BY name

Refresh

مثل Dashboard.

refreshProducts()

refreshProducts()

Repository:

API
↓
Room

نه:

API
↓
Compose

اگر اینترنت قطع بود

چون Room منبع اصلیه: محصولات همچنان نمایش داده میشن.

تنها چیزی که نداریم: آخرین تغییرات سروره.

Empty State

اگر فروشگاه هنوز هیچ محصولی نداره: نباید لیست خالی نمایش بدیم.

بهتره:
هنوز محصولی ثبت نکردی.
اولین محصولت رو اضافه کن.

به همراه دکمه:
افزودن محصول

Error

اگر:

Room خالی

+

API هم شکست خورد

آنگاه:

خطا در دریافت اطلاعات

نمایش داده میشه.

این با Empty فرق داره.

چرا همه محصولات یکجا دانلود نشن؟

فرض کن:

۸۰ هزار کالا

اگر همه رو یکجا بگیریم:

• دانلود طولانی
• حافظه زیاد
• شروع کند برنامه

به همین دلیل، در پروژه‌های بزرگ معمولاً داده‌ها به‌صورت صفحه‌ای (Pagination) دریافت میشن؛ یعنی فقط بخشی از محصولات دانلود میشه و با اسکرول کاربر، صفحه‌های بعدی به‌تدریج دریافت میشن.

در نسخه اولیه قیمت‌بان، اگر تعداد محصولات هر فروشگاه محدود باشه، می‌تونیم فعلاً کل لیست رو دریافت کنیم. اما باید بدونیم این راهکار برای مقیاس‌های بزرگ مناسب نیست.

اسکرول روان

فرض کن:

۲۰۰۰ محصول

اگر ProductItem سنگین باشه: اسکرول گیر می‌کنه.

بهتره ProductItem فقط اطلاعات ضروری رو نمایش بده:

• تصویر
• نام
• قیمت

نه اینکه داخل هر آیتم:

• درخواست اینترنت
• Query دیتابیس
• محاسبات سنگین

انجام بشه.

کلیک روی محصول

viewModel.onProductClick(
    product.id
)

viewModel.onProductClick(
    product.id
)

باز هم:

id

نه کل Product.

چون مقصد بعدی خودش اطلاعات کامل رو از Repository می‌گیره. این کار وابستگی بین صفحه‌ها رو کمتر می‌کنه.

حذف محصول از لیست

فرض کن یک محصول حذف شد. اگر:

key = { it.id }

key = { it.id }

وجود داشته باشه، Compose فقط همون آیتم رو حذف می‌کنه. نه اینکه کل لیست دوباره ساخته بشه.

مسئولیت هر بخش

Compose نمایش لیست کلیک روی محصول ↓ ViewModel مدیریت State ↓ Repository Sync ↓ API ↓ Room

همان معماری آشنای MVVM دوباره تکرار میشه.

تفاوت Refresh و Sync

گاهی این دو مفهوم با هم اشتباه گرفته میشن. Refresh یعنی کاربر یا برنامه درخواست می‌کنه داده‌های جدید از سرور دریافت بشن. اما Sync مفهوم بزرگ‌تریه؛ یعنی هماهنگ کردن اطلاعات بین سرور و حافظه محلی. ممکنه Sync فقط داده‌های جدید رو اضافه کنه، بعضی محصولات حذف‌شده رو پاک کنه یا تغییرات موجود رو به‌روزرسانی کنه.

پس هر Refresh معمولاً باعث شروع یک Sync میشه، اما Sync فقط به معنی دوباره دانلود کردن همه چیز نیست.

چرا محصولات مهم‌ترین صفحه برنامه هستن؟

تقریباً تمام عملیات بعدی از همین صفحه شروع میشن. کاربر از اینجا وارد:

• جزئیات محصول
• ویرایش محصول
• ثبت قیمت
• حذف محصول
• جستجو
• فیلتر

میشه. به همین دلیل اگر معماری این صفحه درست طراحی بشه، تقریباً تمام بخش‌های بعدی برنامه هم ساده‌تر و تمیزتر خواهند شد. در نهایت، مسیر مشاهده محصولات در قیمت‌بان رو میشه این‌طور خلاصه کرد:

برنامه فهرست محصولات رو از سرور دریافت و داخل Room ذخیره می‌کنه، ViewModel آخرین نسخه محصولات رو به‌صورت Flow دریافت می‌کنه و Compose با استفاده از LazyColumn فقط آیتم‌های قابل مشاهده رو نمایش میده تا حتی با تعداد زیاد محصولات، صفحه سریع، روان و قابل نگهداری باقی بمونه.

درس بیست‌ونهم

برنامه چطور بین هزاران محصول در کمتر از چند لحظه جستجو می‌کنه، بدون اینکه هر بار به سرور درخواست جدید بفرسته؟

جستجو

تقریباً هیچ صاحب فروشگاهی دوست نداره هر بار برای پیدا کردن یک کالا، صدها محصول رو اسکرول کنه. فرض کن داخل فروشگاه ۳۰۰۰ محصول وجود داره و کاربر می‌خواد فقط کوکاکولا رو پیدا کنه. طبیعی‌ترین انتظارش اینه که چند حرف اول اسم رو بنویسه و همان لحظه نتیجه ظاهر بشه.

اگر جستجو کند باشه، مهم نیست برنامه چقدر ظاهر زیبایی داشته باشه؛ کاربر احساس می‌کنه کل اپلیکیشن ضعیفه. به همین دلیل، جستجو یکی از مهم‌ترین قابلیت‌های قیمت‌بان محسوب میشه.

در ظاهر فقط یک TextField بالای صفحه دیده میشه، اما پشت همین TextField چند سیستم مختلف با هم همکاری می‌کنن.

TextField
↓
Search Query
↓
ViewModel
↓
Repository
↓
Room Search
↓
Flow
↓
Products List

نکته مهم اینه که در بیشتر مواقع، جستجو نباید مستقیماً به اینترنت وابسته باشه.

چرا جستجو از سرور انجام نمیشه؟

اولین ایده معمولاً اینه:

کاربر تایپ می‌کند
↓
API
↓
نتیجه

مثلاً: کاربر تایپ می‌کنه:

ک

یک درخواست ارسال میشه. بعد:

کو

دوباره درخواست. بعد:

کوک

دوباره درخواست. اگر کاربر فقط یک کلمه پنج حرفی تایپ کنه، پنج درخواست به سرور ارسال شده. این هم اینترنت مصرف می‌کنه، هم سرعت برنامه رو پایین میاره، هم فشار زیادی روی Backend ایجاد می‌کنه.

پس جستجو از کجا انجام میشه؟

چون محصولات داخل Room ذخیره شدن، بهترین جا برای جستجو خود دیتابیسه. مسیر به این شکل میشه:

TextField
↓
Room Query
↓
Flow
↓
UI

یعنی تقریباً هیچ درخواست اینترنتی وجود نداره. همه چیز داخل گوشی انجام میشه.

Search Query

اولین چیزی که باید نگهداری کنیم، متن جستجوست.

مثلاً:

private val _query =
    MutableStateFlow("")

private val _query =
    MutableStateFlow("")

نسخه عمومی:

val query =
    _query.asStateFlow()

val query =
    _query.asStateFlow()

هر بار کاربر چیزی تایپ می‌کنه:

fun onQueryChanged(
    value:String
){
    _query.value = value
}

fun onQueryChanged(
    value:String
){
    _query.value = value
}

دقیقاً مثل TextFieldهای قبلی.

چرا Query داخل ViewModel است؟

ممکنه بگی: با rememberSaveable هم میشه. درسته. اما Query فقط یک TextField نیست. کل لیست محصولات به اون وابسته است. اگر Query داخل ViewModel باشه:

• صفحه بچرخه.
• Navigation انجام بشه.
• صفحه دوباره ساخته بشه.

جستجو از بین نمیره.

Repository

Repository تابع جستجو داره.

fun searchProducts(
    query:String
)

fun searchProducts(
    query:String
)

اما این تابع بهتره Flow برگردونه.

Flow<List<Product>>

Flow<List<Product>>

چون هر بار نتیجه تغییر می‌کنه.

DAO

قسمت مهم جستجو اینجاست.

SELECT *

FROM Product

WHERE name LIKE '%' || :query || '%'

SELECT *

FROM Product

WHERE name LIKE '%' || :query || '%'

این Query میگه:

هر محصولی که اسمش شامل متن جستجو باشه برگردون.

مثلاً:

Query:

کوک

نتیجه:

کوکاکولا

کوکی شکلاتی

LIKE یعنی چه؟

فرض کن:

کوک

اگر بنویسیم:

WHERE name = :query

فقط محصولی پیدا میشه که دقیقاً اسمش:

کوک

باشه.

اما:

LIKE

جستجوی جزئی انجام میده.

علامت %

در SQL:

%

یعنی:

هر تعداد کاراکتر.

مثلاً:

%کوک%

یعنی:

هر اسمی که داخلش:

کوک

وجود داشته باشه.

جستجو با Flow

Repository:

fun searchProducts(
    query:String
)=
productDao.search(query)

fun searchProducts(
    query:String
)=
productDao.search(query)

ViewModel:

به جای اینکه هر بار دستی Search رو صدا بزنیم، بهتره Query رو به یک جریان نتایج تبدیل کنیم.

val products =
    query.flatMapLatest {

        repository.searchProducts(it)

    }

val products =
    query.flatMapLatest {

        repository.searchProducts(it)

    }

این یکی از مهم‌ترین کدهای این درسه.

flatMapLatest

فرض کن کاربر سریع تایپ می‌کنه.

ک
↓
کو
↓
کوک
↓
کوکا

اگر همه جستجوها ادامه پیدا کنن:

ممکنه نتیجه:

ک

بعد از:

کوکا

برسه.

در نتیجه لیست اشتباه نمایش داده میشه.

اما:

flatMapLatest

تمام جستجوهای قبلی رو لغو می‌کنه. فقط آخرین Query معتبر باقی می‌مونه. این دقیقاً همون رفتاریه که برای جستجوی زنده نیاز داریم.

چرا Query خالی هم جستجو میشه؟

وقتی کاربر چیزی ننوشته:

""

دو انتخاب داریم.

اول:

هیچ نتیجه‌ای نمایش ندیم.

دوم:

همه محصولات رو نمایش بدیم.

برای قیمت‌بان، گزینه دوم منطقی‌تره.

پس داخل Repository:

if(query.isBlank()){

    observeProducts()

}
else{

    searchProducts(query)

}

if(query.isBlank()){

    observeProducts()

}
else{

    searchProducts(query)

}

Debounce

فرض کن کاربر خیلی سریع تایپ می‌کنه.

ک

کو

کوک

کوکا

لازم نیست بعد از هر حرف Query اجرا بشه. بهتره چند میلی‌ثانیه صبر کنیم. به این کار میگن:

Debounce

مثلاً:

query

.debounce(300)

یعنی: اگر تا ۳۰۰ میلی‌ثانیه چیزی تایپ نشد، جستجو اجرا بشه.

چرا Debounce؟

اگر نباشه:
سلام

پنج بار جستجو اجرا میشه. اما با Debounce فقط یک بار. این هم مصرف CPU رو کمتر می‌کنه، هم تجربه کاربری رو بهتر.

DistinctUntilChanged

گاهی مقدار Query اصلاً تغییر نکرده.

مثلاً:
کوک

دوباره همون:
کوک

نباید دوباره Query اجرا بشه.

برای همین:

distinctUntilChanged()

distinctUntilChanged()

استفاده می‌کنیم.

زنجیره کامل جستجو

در نهایت ViewModel چیزی شبیه این داره:

query

.debounce(300)

.distinctUntilChanged()

.flatMapLatest {

    repository.searchProducts(it)

}

query

.debounce(300)

.distinctUntilChanged()

.flatMapLatest {

    repository.searchProducts(it)

}

این یکی از رایج‌ترین الگوهای Kotlin Flow است.

State صفحه

data class ProductsUiState(

    val query:String="",

    val products:
        List<Product> = emptyList(),

    val isSearching:Boolean=false

)

data class ProductsUiState(

    val query:String="",

    val products:
        List<Product> = emptyList(),

    val isSearching:Boolean=false

)

وقتی Query تغییر می‌کنه:

State هم تغییر می‌کنه.

نمایش TextField

OutlinedTextField(

    value = state.query,

    onValueChange =
        viewModel::onQueryChanged

)

OutlinedTextField(

    value = state.query,

    onValueChange =
        viewModel::onQueryChanged

)

صفحه هیچ اطلاعی از SQL نداره. فقط متن رو به ViewModel میده.

آیا باید جستجو داخل Compose انجام بشه؟

گاهی افراد این کار رو می‌کنن:

products.filter {

    ...

}

products.filter {

    ...

}

داخل Compose.

این روش برای لیست‌های کوچک شاید مشکلی نداشته باشه.

اما اگر:

۵۰۰۰ محصول

وجود داشته باشه،

هر بار تایپ:

کل لیست دوباره پردازش میشه.

در حالی که دیتابیس برای همین کار ساخته شده.

جستجو بر اساس بارکد

گاهی کاربر بارکد رو اسکن می‌کنه.

در این حالت:

Barcode
↓
Search
↓
Product

Repository می‌تونه تابع جدا داشته باشه.

searchByBarcode()

searchByBarcode()

چون بارکد معمولاً دقیقاً برابر است.

نه LIKE.

جستجو روی چند فیلد

گاهی کاربر:

• اسم کالا
• بارکد
• کد محصول

رو جستجو می‌کنه.

در SQL:

WHERE

name LIKE ...

OR

barcode LIKE ...

WHERE

name LIKE ...

OR

barcode LIKE ...

یعنی: اگر هر کدوم پیدا شد، محصول نمایش داده بشه.

آیا حروف بزرگ و کوچک مهمه؟

در فارسی تقریباً نه. اما در انگلیسی ممکنه مهم باشه. بهتره جستجو به حروف حساس نباشه.

مثلاً:

Milk

milk

MILK

همه یک نتیجه بدن. این رفتار معمولاً در سطح دیتابیس یا Collation تنظیم میشه، نه داخل Compose.

نتیجه نداشتن جستجو

اگر محصولی پیدا نشد: نباید فقط لیست خالی ببینیم.

بهتره:
محصولی پیدا نشد.

و حتی:
عبارت دیگری رو امتحان کن.

نمایش داده بشه.

دکمه پاک کردن جستجو

اگر Query خالی نباشه:
یک دکمه:

×

نمایش میدیم.

کلیک:

viewModel.onQueryChanged("")

viewModel.onQueryChanged("")

بعد: همه محصولات دوباره نمایش داده میشن.

آیا Query باید داخل Room ذخیره بشه؟

خیر.

Query داده دائمی نیست. فقط State صفحه است. بنابراین داخل دیتابیس ذخیره نمیشه.

Search History

بعضی برنامه‌ها آخرین جستجوها رو نگه می‌دارن. مثلاً:

کوکاکولا
شیر
دلستر

این قابلیت کاملاً جدا از خود Search است. اگر بعدها خواستیم اضافه کنیم، یک جدول مستقل خواهد داشت. نه جدول Product.

مسئولیت هر بخش

Compose
نمایش TextField
نمایش لیست
↓
ViewModel
نگهداری Query
↓
Repository
Search
↓
Room
اجرای Query

مثل همیشه، هیچ Query دیتابیسی داخل Compose نوشته نمیشه.

جستجو فقط فیلتر کردن یک لیست نیست

در ظاهر، کاربر فقط چند حرف داخل یک TextField تایپ می‌کنه و نتایج تغییر می‌کنن. اما پشت این رفتار ساده، یک جریان واکنشی کامل وجود داره. متن جستجو داخل ViewModel نگهداری میشه، با debounce از اجرای بی‌دلیل جستجو جلوگیری می‌کنیم، distinctUntilChanged مانع اجرای Queryهای تکراری میشه و flatMapLatest فقط آخرین جستجوی معتبر رو نگه می‌داره. Repository هم جستجو رو به Room می‌سپاره و نتایج به‌صورت Flow دوباره به رابط کاربری برمی‌گردن.

مهم‌ترین نکته این درس اینه که جستجو نباید با هر بار تایپ به سرور وابسته باشه. وقتی داده‌ها داخل Room وجود دارن، سریع‌ترین، ارزان‌ترین و پایدارترین محل برای جستجو خود دیتابیس محلیه.

در نهایت، مسیر جستجوی محصولات در قیمت‌بان رو میشه این‌طور خلاصه کرد:

کاربر متن جستجو رو وارد می‌کنه، ViewModel اون رو به یک جریان واکنشی تبدیل می‌کنه، Repository جستجو رو داخل Room انجام میده و Compose فقط نتایج نهایی رو نمایش میده؛ بدون اینکه برای هر حرف تایپ‌شده درخواست جدیدی به سرور ارسال بشه.

درس سی‌ام

برنامه چطور محصولات رو بر اساس قیمت یا زمان ثبت مرتب می‌کنه، بدون اینکه منطق مرتب‌سازی وارد رابط کاربری بشه؟

فیلتر و مرتب‌سازی محصولات

بعد از اینکه کاربر تونست محصولات رو ببینه و بین اون‌ها جستجو کنه، قدم بعدی اینه که ترتیب نمایش نتایج رو تغییر بده. ممکنه بخواد ارزان‌ترین محصولات اول دیده بشن، شاید دنبال گران‌ترین‌ها باشه یا بخواد محصولاتی رو ببینه که تازه‌تر از بقیه ثبت شدن. در ظاهر، کاربر فقط یکی از این گزینه‌ها رو انتخاب می‌کنه: کمترین قیمت، بیشترین قیمت یا جدیدترین.

اما از نظر معماری، باید مشخص کنیم این انتخاب کجا نگهداری میشه، چه کسی اون رو به Query دیتابیس تبدیل می‌کنه و چطور می‌تونیم جستجو و مرتب‌سازی رو هم‌زمان با هم اجرا کنیم. مسیر کلی به این شکله: کاربر گزینه مرتب‌سازی رو انتخاب می‌کنه، ViewModel انتخاب فعلی رو نگه می‌داره، Repository متناسب با اون تصمیم می‌گیره کدوم Query اجرا بشه، Room محصولات رو با ترتیب درست برمی‌گردونه و Compose فقط لیست نهایی رو نمایش میده.

نکته مهم اینه که خود Compose نباید لیست محصولات رو بر اساس قیمت مرتب کنه. رابط کاربری فقط باید بگه کاربر چه نوع ترتیبی رو انتخاب کرده؛ اجرای واقعی مرتب‌سازی وظیفه لایه داده است.

فیلتر یا مرتب‌سازی؟

در گفتگوهای روزمره معمولاً به همه این گزینه‌ها فیلتر می‌گیم، اما از نظر فنی تفاوتی وجود داره. فیلتر یعنی بخشی از داده‌ها حذف بشن. مثلاً فقط محصولات دسته نوشیدنی نمایش داده بشن یا فقط محصولاتی دیده بشن که قیمت دارن. مرتب‌سازی یعنی همه داده‌ها باقی بمونن، اما ترتیب اون‌ها عوض بشه. مثلاً محصولات از ارزان به گران یا از جدید به قدیم نمایش داده بشن.

پس گزینه‌های کمترین قیمت، بیشترین قیمت و جدیدترین، در اصل مرتب‌سازی هستن، نه فیلتر. با این حال، ممکنه در رابط کاربری عنوان دکمه فیلتر باشه، چون برای کاربر قابل فهم‌تره.

چرا مرتب‌سازی نباید داخل Compose انجام بشه؟

ممکنه ساده‌ترین راه این به نظر برسه که محصولات رو بگیریم و داخل صفحه بنویسیم:

val sortedProducts = products.sortedBy { it.lastPrice }

val sortedProducts = products.sortedBy { it.lastPrice }

این کد واقعاً Kotlin است، اما برای معماری قیمت‌بان انتخاب مناسبی نیست. اول اینکه تمام محصولات باید از دیتابیس وارد حافظه بشن و بعد مرتب بشن. دوم اینکه با هر تغییر State ممکنه دوباره مرتب‌سازی انجام بشه. سوم اینکه اگر بعدها Pagination داشته باشیم، مرتب کردن فقط محصولاتی که فعلاً در حافظه هستن، ترتیب واقعی کل داده‌ها رو مشخص نمی‌کنه.

دیتابیس برای مرتب‌سازی ساخته شده. Room می‌تونه قبل از برگردوندن داده‌ها، اون‌ها رو با ORDER BY مرتب کنه. در نتیجه فقط خروجی نهایی و آماده نمایش به برنامه میرسه.

مدل انتخاب مرتب‌سازی

بهتره به جای نگهداری یک متن ساده مثل کمترین قیمت، یک نوع مشخص برای حالت‌های مرتب‌سازی بسازیم:

enum class ProductSort {
    LOWEST_PRICE,
    HIGHEST_PRICE,
    NEWEST
}

enum class ProductSort {
    LOWEST_PRICE,
    HIGHEST_PRICE,
    NEWEST
}

این کد در لایه Presentation یا در یک بخش مشترک مربوط به محصولات قرار می‌گیره. دلیل وجودش اینه که ViewModel به یک مقدار پایدار و قابل اطمینان نیاز داره. اگر متن قابل نمایش رو مستقیماً نگه داریم، ممکنه بعداً متن فارسی تغییر کنه یا برنامه چندزبانه بشه. اما مقدار LOWEST_PRICE همچنان همون مفهوم قبلی رو حفظ می‌کنه. متن‌هایی مثل کمترین قیمت فقط در UI به این مقادیر تبدیل میشن. منطق برنامه نباید به متن دکمه وابسته باشه.

نگهداری انتخاب داخل ViewModel

حالت مرتب‌سازی، مثل متن جستجو، بخشی از State صفحه است. بنابراین بهتره داخل ViewModel نگهداری بشه:

private val _sort =
    MutableStateFlow(ProductSort.NEWEST)

val sort = _sort.asStateFlow()

private val _sort =
    MutableStateFlow(ProductSort.NEWEST)

val sort = _sort.asStateFlow()

در این مثال، حالت پیش‌فرض NEWEST است. یعنی وقتی کاربر برای اولین بار وارد صفحه میشه، جدیدترین محصولات اول دیده میشن.

مقدار پیش‌فرض باید با نیاز واقعی قیمت‌بان انتخاب بشه. برای بعضی فروشگاه‌ها مرتب‌سازی الفبایی ممکنه منطقی‌تر باشه، اما بین سه گزینه‌ای که فعلاً داریم، جدیدترین انتخاب مناسبیه چون محصول تازه ثبت‌شده سریع‌تر در دسترس قرار می‌گیره.

وقتی کاربر گزینه دیگری رو انتخاب می‌کنه، ViewModel فقط State رو تغییر میده:

fun onSortChanged(sort: ProductSort) {
    _sort.value = sort
}

fun onSortChanged(sort: ProductSort) {
    _sort.value = sort
}

این تابع هیچ Queryای اجرا نمی‌کنه و هیچ لیستی رو مرتب نمی‌کنه. فقط میگه انتخاب فعلی کاربر تغییر کرده.

Query کمترین قیمت

برای نمایش محصولات از ارزان به گران، Query باید بر اساس قیمت صعودی مرتب بشه:

@Query(
    """
    SELECT * FROM products
    ORDER BY lastPrice ASC
    """
)
fun observeByLowestPrice(): Flow<List<ProductEntity>>

@Query(
    """
    SELECT * FROM products
    ORDER BY lastPrice ASC
    """
)
fun observeByLowestPrice(): Flow<List<ProductEntity>>

ASC مخفف Ascending است؛ یعنی ترتیب صعودی. قیمت‌های کوچک‌تر در ابتدای لیست قرار می‌گیرن و هرچه پایین‌تر میریم، قیمت بیشتر میشه. این Query داخل ProductDao قرار می‌گیره، چون اجرای SQL مسئولیت DAO است.

Query بیشترین قیمت

برای نمایش محصولات از گران به ارزان، فقط جهت مرتب‌سازی عوض میشه:

@Query(
    """
    SELECT * FROM products
    ORDER BY lastPrice DESC
    """
)
fun observeByHighestPrice(): Flow<List<ProductEntity>>

@Query(
    """
    SELECT * FROM products
    ORDER BY lastPrice DESC
    """
)
fun observeByHighestPrice(): Flow<List<ProductEntity>>

DESC یعنی ترتیب نزولی. قیمت‌های بزرگ‌تر اول نمایش داده میشن.

نکته مهم اینه که Repository یا ViewModel نباید خودش ASC و DESC تولید کنه و به SQL تزریق کنه. Queryهای مشخص و از پیش تعریف‌شده، هم خواناتر هستن و هم احتمال خطا رو کمتر می‌کنن.

Query جدیدترین محصولات

برای مرتب‌سازی بر اساس زمان ثبت، محصول باید یک فیلد زمانی داشته باشه:

val createdAt: Long

val createdAt: Long

این مقدار می‌تونه Timestamp باشه؛ یعنی عددی که زمان ثبت محصول رو نمایش میده. در این حالت Query جدیدترین‌ها به این شکل میشه:

@Query(
    """
    SELECT * FROM products
    ORDER BY createdAt DESC
    """
)
fun observeNewest(): Flow<List<ProductEntity>>

@Query(
    """
    SELECT * FROM products
    ORDER BY createdAt DESC
    """
)
fun observeNewest(): Flow<List<ProductEntity>>

چون زمان‌های جدیدتر مقدار بزرگ‌تری دارن، با DESC محصولات تازه‌تر اول قرار می‌گیرن. باید مشخص باشه منظور از جدیدترین چیه. ممکنه جدیدترین بر اساس زمان ساخت محصول باشه یا بر اساس آخرین ویرایش. این دو مفهوم یکسان نیستن.

اگر کاربر می‌خواد محصولاتی رو ببینه که تازه به فروشگاه اضافه شدن، باید از createdAt استفاده کنیم. اگر هدف دیدن آخرین محصولات ویرایش‌شده باشه، فیلدی مثل updatedAt مناسب‌تره. در قیمت‌بان، برای گزینه جدیدترین، منطقی‌تره منظور زمان ثبت محصول باشه.

محصول بدون قیمت چه میشه؟

اینجا یک سؤال مهم پیش میاد. فرض کن بعضی محصولات هنوز قیمت ندارن و مقدار lastPrice اون‌ها null است. وقتی بر اساس قیمت مرتب می‌کنیم، باید مشخص کنیم این محصولات کجای لیست قرار بگیرن. اگر هیچ تصمیمی نگیریم، رفتار null ممکنه با چیزی که کاربر انتظار داره متفاوت باشه. برای مثال، در مرتب‌سازی کمترین قیمت ممکنه محصولات بدون قیمت قبل از محصولات ارزان نمایش داده بشن، چون null از نظر دیتابیس قیمت واقعی محسوب نمیشه.

اما از دید کاربر، محصول بدون قیمت نباید به‌عنوان ارزان‌ترین محصول دیده بشه. بهتره محصولات قیمت‌دار اول نمایش داده بشن و موارد بدون قیمت در انتهای لیست قرار بگیرن.

می‌تونیم این تصمیم رو داخل Query مشخص کنیم:

@Query(
    """
    SELECT * FROM products
    ORDER BY
        CASE WHEN lastPrice IS NULL THEN 1 ELSE 0 END,
        lastPrice ASC
    """
)
fun observeByLowestPrice(): Flow<List<ProductEntity>>

@Query(
    """
    SELECT * FROM products
    ORDER BY
        CASE WHEN lastPrice IS NULL THEN 1 ELSE 0 END,
        lastPrice ASC
    """
)
fun observeByLowestPrice(): Flow<List<ProductEntity>>

بخش CASE ابتدا محصولات رو به دو گروه تقسیم می‌کنه. محصولاتی که قیمت دارن مقدار صفر می‌گیرن و قبل‌تر قرار می‌گیرن. محصولاتی که قیمت ندارن مقدار یک می‌گیرن و به انتهای لیست میرن. بعد داخل گروه محصولات قیمت‌دار، مرتب‌سازی بر اساس قیمت انجام میشه.

این مثال نشون میده مرتب‌سازی فقط نوشتن ASC یا DESC نیست؛ باید رفتار داده‌های ناقص هم مشخص بشه.

برای بیشترین قیمت هم می‌تونیم همین منطق رو نگه داریم و فقط جهت قیمت رو تغییر بدیم:

@Query(
    """
    SELECT * FROM products
    ORDER BY
        CASE WHEN lastPrice IS NULL THEN 1 ELSE 0 END,
        lastPrice DESC
    """
)
fun observeByHighestPrice(): Flow<List<ProductEntity>>

@Query(
    """
    SELECT * FROM products
    ORDER BY
        CASE WHEN lastPrice IS NULL THEN 1 ELSE 0 END,
        lastPrice DESC
    """
)
fun observeByHighestPrice(): Flow<List<ProductEntity>>

در هر دو حالت، محصولات بدون قیمت در انتها قرار می‌گیرن.

Repository چطور Query مناسب رو انتخاب می‌کنه؟

ViewModel نباید بدونه کدوم تابع DAO باید اجرا بشه. این تصمیم در Repository گرفته میشه:

fun observeProducts(
    sort: ProductSort
): Flow<List<Product>> {
    val source = when (sort) {
        ProductSort.LOWEST_PRICE ->
            productDao.observeByLowestPrice()

        ProductSort.HIGHEST_PRICE ->
            productDao.observeByHighestPrice()

        ProductSort.NEWEST ->
            productDao.observeNewest()
    }

    return source.map { entities ->
        entities.map(ProductEntity::toDomain)
    }
}

fun observeProducts(
    sort: ProductSort
): Flow<List<Product>> {
    val source = when (sort) {
        ProductSort.LOWEST_PRICE ->
            productDao.observeByLowestPrice()

        ProductSort.HIGHEST_PRICE ->
            productDao.observeByHighestPrice()

        ProductSort.NEWEST ->
            productDao.observeNewest()
    }

    return source.map { entities ->
        entities.map(ProductEntity::toDomain)
    }
}

این تابع در ProductRepository قرار می‌گیره. ViewModel فقط نوع مرتب‌سازی رو می‌فرسته و Repository منبع مناسب داده رو انتخاب می‌کنه.

تبدیل Entity به مدل Domain هم در همین مسیر انجام میشه تا UI مستقیماً با مدل دیتابیس کار نکنه.

تبدیل State مرتب‌سازی به لیست محصولات

در ViewModel، با تغییر گزینه مرتب‌سازی باید Flow محصولات هم تغییر کنه. برای این کار دوباره flatMapLatest کاربرد داره:

val products =
    sort.flatMapLatest { selectedSort ->
        repository.observeProducts(selectedSort)
    }

val products =
    sort.flatMapLatest { selectedSort ->
        repository.observeProducts(selectedSort)
    }

وقتی مقدار sort تغییر می‌کنه، Flow قبلی کنار گذاشته میشه و Repository جریان جدیدی با ترتیب تازه می‌سازه.

برای مثال، صفحه ابتدا NEWEST رو مشاهده می‌کنه. کاربر کمترین قیمت رو انتخاب می‌کنه. جریان جدیدی از Room ساخته میشه که محصولات رو بر اساس lastPrice ASC برمی‌گردونه. Compose هم نتیجه جدید رو دریافت می‌کنه و ترتیب لیست تغییر می‌کنه.

نکته مهم اینه که داده‌ها دوباره از سرور دانلود نمیشن. فقط Query محلی تغییر می‌کنه.

ترکیب جستجو و مرتب‌سازی

در درس قبل، متن جستجو رو داشتیم. حالا مرتب‌سازی هم اضافه شده. کاربر ممکنه ابتدا شیر رو جستجو کنه و بعد بخواد نتایج همون جستجو از ارزان به گران نمایش داده بشن.

پس نتیجه نهایی باید به دو State وابسته باشه:

متن جستجو و نوع مرتب‌سازی.

برای ترکیب این دو از combine استفاده می‌کنیم:

val products =
    combine(
        query.debounce(300),
        sort
    ) { queryValue, sortValue ->
        queryValue.trim() to sortValue
    }.flatMapLatest { (queryValue, sortValue) ->
        repository.observeProducts(
            query = queryValue,
            sort = sortValue
        )
    }

val products =
    combine(
        query.debounce(300),
        sort
    ) { queryValue, sortValue ->
        queryValue.trim() to sortValue
    }.flatMapLatest { (queryValue, sortValue) ->
        repository.observeProducts(
            query = queryValue,
            sort = sortValue
        )
    }

combine هر بار که Query یا Sort تغییر کنه، آخرین مقدار هر دو رو کنار هم قرار میده.

اگر کاربر متن جستجو رو تغییر بده، نتیجه تازه گرفته میشه. اگر فقط نوع مرتب‌سازی رو تغییر بده، همون متن جستجو حفظ میشه و فقط ترتیب نتایج عوض میشه.

flatMapLatest هم تضمین می‌کنه فقط آخرین ترکیب معتبر ادامه پیدا کنه. مثلاً اگر کاربر هم‌زمان سریع تایپ کنه و گزینه مرتب‌سازی رو عوض کنه، جریان‌های قبلی کنار گذاشته میشن.

Repository برای جستجو و مرتب‌سازی

وقتی جستجو و مرتب‌سازی هم‌زمان وجود دارن، Repository باید هر دو رو دریافت کنه:

fun observeProducts(
    query: String,
    sort: ProductSort
): Flow<List<Product>>

fun observeProducts(
    query: String,
    sort: ProductSort
): Flow<List<Product>>

اما اینجا یک مسئله طراحی ایجاد میشه. اگر برای هر حالت Query جدا بنویسیم، حداقل به شش Query نیاز داریم:

جستجوی کمترین قیمت، جستجوی بیشترین قیمت، جستجوی جدیدترین و همین سه حالت برای زمانی که متن جستجو خالیه.

در پروژه کوچک این تعداد هنوز قابل مدیریت است، اما با اضافه شدن دسته‌بندی، وضعیت قیمت، برند و فیلترهای بیشتر، تعداد ترکیب‌ها خیلی زیاد میشه.

برای نسخه فعلی قیمت‌بان، می‌تونیم Queryهای روشن و مشخص داشته باشیم، چون فقط سه نوع مرتب‌سازی و یک متن جستجو داریم. این روش از ساختن SQL پویا ساده‌تر و امن‌تره.

مثلاً Query جستجو با کمترین قیمت می‌تونه این شکل رو داشته باشه:

@Query(
    """
    SELECT * FROM products
    WHERE name LIKE '%' || :query || '%'
       OR barcode LIKE '%' || :query || '%'
    ORDER BY
        CASE WHEN lastPrice IS NULL THEN 1 ELSE 0 END,
        lastPrice ASC
    """
)
fun searchByLowestPrice(
    query: String
): Flow<List<ProductEntity>>

@Query(
    """
    SELECT * FROM products
    WHERE name LIKE '%' || :query || '%'
       OR barcode LIKE '%' || :query || '%'
    ORDER BY
        CASE WHEN lastPrice IS NULL THEN 1 ELSE 0 END,
        lastPrice ASC
    """
)
fun searchByLowestPrice(
    query: String
): Flow<List<ProductEntity>>

هم جستجو داخل Room انجام میشه و هم مرتب‌سازی. Compose هیچ فیلتر یا Sort اضافه‌ای روی نتیجه اجرا نمی‌کنه.

آیا برای مرتب‌سازی باید دوباره API صدا زده بشه؟

در معماری فعلی قیمت‌بان، نه. چون محصولات قبلاً داخل Room ذخیره شدن، مرتب‌سازی روی داده محلی انجام میشه. وقتی کاربر از جدیدترین به بیشترین قیمت تغییر میده، هیچ نیازی به اینترنت نیست. فقط Query دیتابیس تغییر می‌کنه و Flow نتیجه جدید رو منتشر می‌کنه.

اما اگر تعداد محصولات بسیار زیاد باشه و فقط بخشی از داده‌ها داخل گوشی وجود داشته باشه، شرایط فرق می‌کنه. فرض کن سرور صد هزار محصول داره اما برنامه فقط بیست محصول اول رو دانلود کرده. در این حالت مرتب کردن همین بیست محصول به معنی پیدا کردن ارزان‌ترین محصول کل سرور نیست. در چنین معماری‌ای، نوع مرتب‌سازی باید به API ارسال بشه و سرور داده‌ها رو به ترتیب درست صفحه‌بندی کنه. مثلاً درخواست می‌تونه از نظر مفهومی شامل sort=price_asc باشه.

پس قانون کلی اینه: اگر تمام داده‌های موردنیاز داخل Room هستن، مرتب‌سازی محلی انجام میشه. اگر فقط بخشی از داده‌ها به‌صورت Pagination دریافت شدن، مرتب‌سازی باید از سمت سرور پشتیبانی بشه.

برای نسخه فعلی قیمت‌بان که محصولات هر کسب‌وکار داخل Room قرار می‌گیرن، مرتب‌سازی محلی ساده‌تر و سریع‌تره.

نمایش گزینه‌ها در رابط کاربری

در Compose می‌تونیم گزینه‌ها رو داخل یک Bottom Sheet، Dropdown Menu یا مجموعه‌ای از Chipها نمایش بدیم. انتخاب دقیق رابط به طراحی صفحه بستگی داره، اما خود Composable نباید چیزی درباره SQL بدونه.

بخش مهم اینه که انتخاب کاربر به مقدار ProductSort تبدیل بشه:

FilterChip(
    selected = selectedSort == ProductSort.LOWEST_PRICE,
    onClick = {
        onSortChanged(ProductSort.LOWEST_PRICE)
    },
    label = {
        Text("کمترین قیمت")
    }
)

FilterChip(
    selected = selectedSort == ProductSort.LOWEST_PRICE,
    onClick = {
        onSortChanged(ProductSort.LOWEST_PRICE)
    },
    label = {
        Text("کمترین قیمت")
    }
)

این Composable فقط وضعیت انتخاب‌شده رو دریافت می‌کنه و Callback رو اجرا می‌کنه. ViewModel مستقیماً داخل آیتم UI ساخته نمیشه. برای گزینه‌های دیگر هم همین الگو تکرار میشه، اما لازم نیست کل صفحه یا تمام Chipها رو در جزوه بنویسیم.

نمایش انتخاب فعلی

کاربر باید بدونه الان چه ترتیبی فعاله. اگر دکمه فیلتر رو بزنه و گزینه‌ای انتخاب کنه، بعد از بسته شدن پنجره هم بهتره انتخاب فعلی در UI مشخص باشه. مثلاً عنوان دکمه می‌تونه از مرتب‌سازی به کمترین قیمت تغییر کنه یا Chip مربوط به اون حالت انتخاب‌شده نمایش داده بشه.

اما متن قابل نمایش نباید داخل ViewModel تولید بشه. ViewModel فقط ProductSort.LOWEST_PRICE رو نگه می‌داره و UI تصمیم می‌گیره متن فارسی اون چی باشه. این جداسازی برای چندزبانه شدن برنامه هم مهمه. منطق برنامه ثابت می‌مونه و فقط منابع متنی تغییر می‌کنن.

آیا انتخاب مرتب‌سازی باید حفظ بشه؟

اگر کاربر از صفحه جزئیات محصول برگرده، بهتره مرتب‌سازی قبلی حفظ شده باشه. چون State داخل ViewModel قرار داره، تا زمانی که همون ViewModel زنده است، انتخاب از بین نمیره.

اما اگر برنامه کاملاً بسته و دوباره باز بشه، حالت پیش‌فرض برمی‌گرده. اینکه انتخاب کاربر برای دفعات بعد هم ذخیره بشه یا نه، یک تصمیم محصولیه. اگر این ترجیح برای کاربر مهم باشه، می‌تونیم مقدار Sort رو داخل DataStore ذخیره کنیم. اما نباید برای یک State ساده صفحه، بدون نیاز واقعی ذخیره‌سازی دائمی اضافه کنیم. برای نسخه اولیه، حفظ شدن انتخاب در همان Session کافی است.

تغییر مرتب‌سازی نباید Loading تمام‌صفحه بسازه

چون داده‌ها از Room میان، تغییر ترتیب معمولاً بسیار سریعه. بنابراین وقتی کاربر گزینه بیشترین قیمت رو انتخاب می‌کنه، نباید کل صفحه وارد Loading بشه و لیست ناپدید بشه. لیست قبلی می‌تونه تا زمان رسیدن خروجی جدید باقی بمونه و بعد ترتیبش تغییر کنه. در بیشتر موارد این تغییر آن‌قدر سریع انجام میشه که حتی Loading جداگانه لازم نیست. Loading تمام‌صفحه فقط زمانی منطقیه که هیچ داده‌ای برای نمایش نداریم. تغییر Sort یک عملیات محلی کوتاهه، نه بارگذاری اولیه صفحه.

ترتیب پایدار برای قیمت‌های برابر

فرض کن چند محصول دقیقاً قیمت یکسان دارن. اگر فقط بر اساس قیمت مرتب کنیم، ترتیب اون‌ها ممکنه بین اجراهای مختلف ثابت نباشه. برای اینکه نتیجه پایدار باشه، یک معیار دوم اضافه می‌کنیم:

@Query(
    """
    SELECT * FROM products
    ORDER BY
        CASE WHEN lastPrice IS NULL THEN 1 ELSE 0 END,
        lastPrice ASC,
        name ASC
    """
)
fun observeByLowestPrice(): Flow<List<ProductEntity>>

@Query(
    """
    SELECT * FROM products
    ORDER BY
        CASE WHEN lastPrice IS NULL THEN 1 ELSE 0 END,
        lastPrice ASC,
        name ASC
    """
)
fun observeByLowestPrice(): Flow<List<ProductEntity>>

ابتدا محصولات بر اساس قیمت مرتب میشن. اگر قیمت دو محصول برابر بود، نام اون‌ها ترتیب نهایی رو مشخص می‌کنه.

این موضوع شاید در ظاهر کوچک به نظر برسه، اما باعث میشه لیست بی‌دلیل جابه‌جا نشه و تجربه کاربر پایدارتر باشه.