feat: 수원대 포털 연동 API 3종 및 에러 매핑 레이어 추가

.gitignore

@@ -47,3 +47,6 @@ app/.idea/
 /composeApp/google-services.json
 /iosApp/iosApp/GoogleService-Info.plist
 /iosApp/Configuration/Config.xcconfig
+
+# Cloned reference repo
+/chukchuk-haksa/

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/data/portal/datasource/PortalRemoteDataSource.kt

@@ -0,0 +1,9 @@
+package com.chukchukhaksa.mobile.data.portal.datasource
+
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingResult
+
+interface PortalRemoteDataSource {
+    suspend fun login(username: String, password: String)
+    suspend fun startScraping(): ScrapingResult
+    suspend fun refreshScraping(): ScrapingResult
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/data/portal/di/PortalRepositoryModule.kt

@@ -0,0 +1,12 @@
+package com.chukchukhaksa.mobile.data.portal.di
+
+import com.chukchukhaksa.mobile.data.portal.datasource.PortalRemoteDataSource
+import com.chukchukhaksa.mobile.data.portal.repository.PortalRepositoryImpl
+import com.chukchukhaksa.mobile.domain.portal.repository.PortalRepository
+import com.chukchukhaksa.mobile.remote.portal.PortalRemoteDataSourceImpl
+import org.koin.dsl.module
+
+val portalRepositoryModule = module {
+    single<PortalRemoteDataSource> { PortalRemoteDataSourceImpl(get()) }
+    single<PortalRepository> { PortalRepositoryImpl(get()) }
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/data/portal/repository/PortalRepositoryImpl.kt

@@ -0,0 +1,22 @@
+package com.chukchukhaksa.mobile.data.portal.repository
+
+import com.chukchukhaksa.mobile.data.portal.datasource.PortalRemoteDataSource
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingResult
+import com.chukchukhaksa.mobile.domain.portal.repository.PortalRepository
+
+class PortalRepositoryImpl(
+    private val portalRemoteDataSource: PortalRemoteDataSource,
+) : PortalRepository {
+
+    override suspend fun login(username: String, password: String) {
+        portalRemoteDataSource.login(username, password)
+    }
+
+    override suspend fun startScraping(): ScrapingResult {
+        return portalRemoteDataSource.startScraping()
+    }
+
+    override suspend fun refreshScraping(): ScrapingResult {
+        return portalRemoteDataSource.refreshScraping()
+    }
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/di/DomainModules.kt

@@ -6,6 +6,9 @@ import com.chukchukhaksa.mobile.domain.auth.usecase.AppleLoginUseCase
 import com.chukchukhaksa.mobile.domain.auth.usecase.CheckAuthStateUseCase
 import com.chukchukhaksa.mobile.domain.auth.usecase.KakaoLoginUseCase
 import com.chukchukhaksa.mobile.domain.config.usecase.CheckNeedForceUpdateUseCase
+import com.chukchukhaksa.mobile.domain.portal.usecase.PortalLoginUseCase
+import com.chukchukhaksa.mobile.domain.portal.usecase.RefreshPortalScrapingUseCase
+import com.chukchukhaksa.mobile.domain.portal.usecase.StartPortalScrapingUseCase
 import com.chukchukhaksa.mobile.domain.profile.usecase.GetProfileUseCase
 import com.chukchukhaksa.mobile.domain.timetable.usecase.DeleteTimetableCellUseCase
 import com.chukchukhaksa.mobile.domain.timetable.usecase.DeleteTimetableUseCase
@@ -58,4 +61,9 @@ val domainModule = module {
     // Academic use cases
     factory { GetAcademicSummaryUseCase(get()) }
     factory { GetAcademicRecordUseCase(get()) }
+
+    // Portal use cases
+    factory { PortalLoginUseCase(get()) }
+    factory { StartPortalScrapingUseCase(get()) }
+    factory { RefreshPortalScrapingUseCase(get()) }
 }

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/di/InitKoin.kt

@@ -5,6 +5,7 @@ import com.chukchukhaksa.mobile.data.auth.di.authRepositoryModule
 import com.chukchukhaksa.mobile.data.config.di.appConfigRepositoryModule
 import com.chukchukhaksa.mobile.data.openlecture.di.openLectureRepositoryModule
 import com.chukchukhaksa.mobile.data.openmajor.di.openMajorRepositoryModule
+import com.chukchukhaksa.mobile.data.portal.di.portalRepositoryModule
 import com.chukchukhaksa.mobile.data.profile.di.ProfileRepositoryModule
 import com.chukchukhaksa.mobile.data.timetable.di.timetableRepositoryModule
 import com.chukchukhaksa.mobile.local.database.common.di.openLectureDatabaseModule
@@ -48,6 +49,7 @@ fun initKoin(config: KoinAppDeclaration? = null) {
             authRepositoryModule,
             ProfileRepositoryModule,
             AcademicRepositoryModule,
+            portalRepositoryModule,
         )
     }
 }

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/domain/portal/model/PortalScrapingError.kt

@@ -0,0 +1,39 @@
+package com.chukchukhaksa.mobile.domain.portal.model
+
+sealed class PortalScrapingError(val defaultMessage: String) {
+
+    data object InvalidCredentials : PortalScrapingError(
+        "아이디나 비밀번호가 일치하지 않습니다.\n학교 홈페이지에서 확인해주세요.",
+    )
+
+    data object AccountLocked : PortalScrapingError(
+        "계정이 잠겼습니다. 포털사이트에서 비밀번호 재설정을 진행해주세요.",
+    )
+
+    data object InvalidAcademicRecord : PortalScrapingError(
+        "입력하신 학적 정보로는 현재 처리가 불가능합니다.\n세부 사유를 확인해주세요.",
+    )
+
+    data object AlreadyConnected : PortalScrapingError(
+        "이미 포털 연동된 학생 정보가 존재합니다.\n다른 계정으로 로그인했는지 확인해주세요.",
+    )
+
+    data object GraduationDataNotFound : PortalScrapingError(
+        "사용자에게 맞는 졸업 요건 데이터가 존재하지 않습니다.\n학과/입학년도 정보를 확인해주세요.",
+    )
+
+    data object DoubleMajorInfoMissing : PortalScrapingError(
+        "복수전공 이수 구분 정보가 존재하지 않아 처리할 수 없습니다.\n학사정보를 확인해주세요.",
+    )
+
+    data object TransferStudentNotSupported : PortalScrapingError(
+        "편입생 학적 정보는 현재 지원되지 않습니다.\n추후 지원 예정입니다.",
+    )
+
+    data class Unknown(
+        val httpStatus: Int?,
+        val appCode: String?,
+    ) : PortalScrapingError(
+        "알 수 없는 오류가 발생했어요.\n잠시 후 다시 시도해주세요.",
+    )
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/domain/portal/model/PortalScrapingException.kt

@@ -0,0 +1,8 @@
+package com.chukchukhaksa.mobile.domain.portal.model
+
+class PortalScrapingException(
+    val error: PortalScrapingError,
+    val httpStatus: Int?,
+    val appCode: String?,
+    override val message: String = error.defaultMessage,
+) : RuntimeException(message)

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/domain/portal/model/ScrapingResult.kt

@@ -0,0 +1,17 @@
+package com.chukchukhaksa.mobile.domain.portal.model
+
+data class ScrapingResult(
+    val taskId: String?,
+    val studentInfo: StudentInfo?,
+    val status: String?,
+)
+
+data class StudentInfo(
+    val name: String?,
+    val school: String?,
+    val majorName: String?,
+    val studentCode: String?,
+    val gradeLevel: Int?,
+    val status: String?,
+    val completedSemesterType: Int?,
+)

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/domain/portal/repository/PortalRepository.kt

@@ -0,0 +1,9 @@
+package com.chukchukhaksa.mobile.domain.portal.repository
+
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingResult
+
+interface PortalRepository {
+    suspend fun login(username: String, password: String)
+    suspend fun startScraping(): ScrapingResult
+    suspend fun refreshScraping(): ScrapingResult
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/domain/portal/usecase/PortalLoginUseCase.kt

@@ -0,0 +1,15 @@
+package com.chukchukhaksa.mobile.domain.portal.usecase
+
+import com.chukchukhaksa.mobile.domain.common.runCatchingIgnoreCancelled
+import com.chukchukhaksa.mobile.domain.portal.repository.PortalRepository
+
+class PortalLoginUseCase(
+    private val portalRepository: PortalRepository,
+) {
+    suspend operator fun invoke(
+        username: String,
+        password: String,
+    ): Result<Unit> = runCatchingIgnoreCancelled {
+        portalRepository.login(username, password)
+    }
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/domain/portal/usecase/RefreshPortalScrapingUseCase.kt

@@ -0,0 +1,13 @@
+package com.chukchukhaksa.mobile.domain.portal.usecase
+
+import com.chukchukhaksa.mobile.domain.common.runCatchingIgnoreCancelled
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingResult
+import com.chukchukhaksa.mobile.domain.portal.repository.PortalRepository
+
+class RefreshPortalScrapingUseCase(
+    private val portalRepository: PortalRepository,
+) {
+    suspend operator fun invoke(): Result<ScrapingResult> = runCatchingIgnoreCancelled {
+        portalRepository.refreshScraping()
+    }
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/domain/portal/usecase/StartPortalScrapingUseCase.kt

@@ -0,0 +1,13 @@
+package com.chukchukhaksa.mobile.domain.portal.usecase
+
+import com.chukchukhaksa.mobile.domain.common.runCatchingIgnoreCancelled
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingResult
+import com.chukchukhaksa.mobile.domain.portal.repository.PortalRepository
+
+class StartPortalScrapingUseCase(
+    private val portalRepository: PortalRepository,
+) {
+    suspend operator fun invoke(): Result<ScrapingResult> = runCatchingIgnoreCancelled {
+        portalRepository.startScraping()
+    }
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/remote/portal/PortalRemoteDataSourceImpl.kt

@@ -0,0 +1,84 @@
+package com.chukchukhaksa.mobile.remote.portal
+
+import com.chukchukhaksa.mobile.data.portal.datasource.PortalRemoteDataSource
+import com.chukchukhaksa.mobile.domain.portal.model.PortalScrapingException
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingResult
+import com.chukchukhaksa.mobile.domain.portal.model.StudentInfo
+import com.chukchukhaksa.mobile.remote.common.ApiResponse
+import com.chukchukhaksa.mobile.remote.portal.model.ScrapingResponseDto
+import com.chukchukhaksa.mobile.remote.portal.model.StudentInfoDto
+import io.ktor.client.HttpClient
+import io.ktor.client.call.body
+import io.ktor.client.request.parameter
+import io.ktor.client.request.post
+import io.ktor.client.statement.HttpResponse
+import kotlinx.serialization.json.JsonObject
+
+class PortalRemoteDataSourceImpl(
+    private val httpClient: HttpClient,
+) : PortalRemoteDataSource {
+
+    override suspend fun login(username: String, password: String) {
+        val httpResponse = httpClient.post("suwon-scrape/login") {
+            parameter("username", username)
+            parameter("password", password)
+        }
+        parseOrThrow<JsonObject>(httpResponse)
+    }
+
+    override suspend fun startScraping(): ScrapingResult {
+        val httpResponse = httpClient.post("suwon-scrape/start")
+        val dto = parseOrThrow<ScrapingResponseDto>(httpResponse)
+        return dto.toDomain()
+    }
+
+    override suspend fun refreshScraping(): ScrapingResult {
+        val httpResponse = httpClient.post("suwon-scrape/refresh")
+        val dto = parseOrThrow<ScrapingResponseDto>(httpResponse)
+        return dto.toDomain()
+    }
+
+    private suspend inline fun <reified T> parseOrThrow(httpResponse: HttpResponse): T {
+        val status = httpResponse.status.value
+        val apiResponse = runCatching {
+            httpResponse.body<ApiResponse<T>>()
+        }.getOrElse { cause ->
+            throw PortalScrapingException(
+                error = mapToPortalScrapingError(httpStatus = status, appCode = null),
+                httpStatus = status,
+                appCode = null,
+                message = cause.message ?: "응답 파싱에 실패했습니다.",
+            )
+        }
+
+        val data = apiResponse.data
+        if (apiResponse.success && data != null) {
+            return data
+        }
+
+        val appCode = apiResponse.error?.code
+        val error = mapToPortalScrapingError(httpStatus = status, appCode = appCode)
+        throw PortalScrapingException(
+            error = error,
+            httpStatus = status,
+            appCode = appCode,
+            message = apiResponse.error?.message ?: error.defaultMessage,
+        )
+    }
+}
+
+private fun ScrapingResponseDto.toDomain() = ScrapingResult(
+    taskId = taskId,
+    studentInfo = studentInfo?.toDomain(),
+    status = status,
+)
+
+private fun StudentInfoDto.toDomain() = StudentInfo(
+    name = name,
+    school = school,
+    majorName = majorName,
+    studentCode = studentCode,
+    gradeLevel = gradeLevel,
+    status = status,
+    completedSemesterType = completedSemesterType,
+)

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/remote/portal/PortalScrapingErrorMapper.kt

@@ -0,0 +1,19 @@
+package com.chukchukhaksa.mobile.remote.portal
+
+import com.chukchukhaksa.mobile.domain.portal.model.PortalScrapingError
+
+internal fun mapToPortalScrapingError(
+    httpStatus: Int?,
+    appCode: String?,
+): PortalScrapingError = when {
+    appCode == "S04" -> PortalScrapingError.AlreadyConnected
+    appCode == "D01" -> PortalScrapingError.DoubleMajorInfoMissing
+    appCode == "T13" -> PortalScrapingError.TransferStudentNotSupported
+    appCode == "G02" -> PortalScrapingError.GraduationDataNotFound
+    httpStatus == 401 -> PortalScrapingError.InvalidCredentials
+    httpStatus == 404 -> PortalScrapingError.GraduationDataNotFound
+    httpStatus == 409 -> PortalScrapingError.AlreadyConnected
+    httpStatus == 422 -> PortalScrapingError.InvalidAcademicRecord
+    httpStatus == 423 -> PortalScrapingError.AccountLocked
+    else -> PortalScrapingError.Unknown(httpStatus = httpStatus, appCode = appCode)
+}

composeApp/src/commonMain/kotlin/com/chukchukhaksa/mobile/remote/portal/model/ScrapingResponseDto.kt

@@ -0,0 +1,21 @@
+package com.chukchukhaksa.mobile.remote.portal.model
+
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class ScrapingResponseDto(
+    val taskId: String? = null,
+    val studentInfo: StudentInfoDto? = null,
+    val status: String? = null,
+)
+
+@Serializable
+data class StudentInfoDto(
+    val name: String? = null,
+    val school: String? = null,
+    val majorName: String? = null,
+    val studentCode: String? = null,
+    val gradeLevel: Int? = null,
+    val status: String? = null,
+    val completedSemesterType: Int? = null,
+)