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,18 @@
+package com.chukchukhaksa.mobile.data.portal.datasource
+
+import com.chukchukhaksa.mobile.remote.portal.model.AcceptedResponseDto
+import com.chukchukhaksa.mobile.remote.portal.model.JobStatusResponseDto
+import com.chukchukhaksa.mobile.remote.portal.model.JobSummaryResponseDto
+
+interface PortalRemoteDataSource {
+    suspend fun createLinkJob(
+        portalType: String,
+        username: String,
+        password: String,
+        idempotencyKey: String,
+    ): AcceptedResponseDto
+
+    suspend fun getJobStatus(jobId: String): JobStatusResponseDto
+
+    suspend fun getJobSummary(jobId: String): JobSummaryResponseDto
+}

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,124 @@
+package com.chukchukhaksa.mobile.data.portal.repository
+
+import com.chukchukhaksa.mobile.data.portal.datasource.PortalRemoteDataSource
+import com.chukchukhaksa.mobile.domain.portal.model.PortalScrapingError
+import com.chukchukhaksa.mobile.domain.portal.model.PortalScrapingException
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingProgress
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingResult
+import com.chukchukhaksa.mobile.domain.portal.model.StudentInfo
+import com.chukchukhaksa.mobile.domain.portal.repository.PortalRepository
+import com.chukchukhaksa.mobile.remote.portal.mapToPortalScrapingError
+import com.chukchukhaksa.mobile.remote.portal.model.JobStatusResponseDto
+import com.chukchukhaksa.mobile.remote.portal.model.JobSummaryResponseDto
+import com.chukchukhaksa.mobile.remote.portal.model.StudentInfoDto
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flow
+
+class PortalRepositoryImpl(
+    private val portalRemoteDataSource: PortalRemoteDataSource,
+) : PortalRepository {
+
+    override fun linkPortal(
+        portalType: String,
+        username: String,
+        password: String,
+        idempotencyKey: String,
+    ): Flow<ScrapingProgress> = flow {
+        val accepted = portalRemoteDataSource.createLinkJob(
+            portalType = portalType,
+            username = username,
+            password = password,
+            idempotencyKey = idempotencyKey,
+        )
+        val jobId = accepted.jobId ?: throw PortalScrapingException(
+            error = PortalScrapingError.Unknown(httpStatus = null, appCode = null),
+            httpStatus = null,
+            appCode = null,
+            retryable = null,
+            message = "포털 연동 job id가 비어있습니다.",
+        )
+
+        emit(ScrapingProgress.Accepted(jobId = jobId))
+
+        repeat(MAX_POLL_COUNT) {
+            delay(POLL_INTERVAL_MS)
+
+            val statusDto = portalRemoteDataSource.getJobStatus(jobId)
+            val jobStatus = statusDto.status.orEmpty()
+
+            when {
+                jobStatus.isTerminalSuccess() -> {
+                    val summary = portalRemoteDataSource.getJobSummary(jobId)
+                    emit(
+                        ScrapingProgress.Completed(
+                            jobId = jobId,
+                            result = summary.toDomain(),
+                        ),
+                    )
+                    return@flow
+                }
+
+                jobStatus.isTerminalFailure() -> {
+                    throw statusDto.toException()
+                }
+
+                else -> emit(
+                    ScrapingProgress.InProgress(
+                        jobId = jobId,
+                        status = jobStatus,
+                    ),
+                )
+            }
+        }
+
+        throw PortalScrapingException(
+            error = PortalScrapingError.Unknown(httpStatus = null, appCode = TIMEOUT_APP_CODE),
+            httpStatus = null,
+            appCode = TIMEOUT_APP_CODE,
+            retryable = null,
+            message = "포털 연동이 시간 내에 완료되지 않았습니다.",
+        )
+    }
+
+    companion object {
+        private const val POLL_INTERVAL_MS = 2_000L
+        private const val MAX_POLL_COUNT = 60
+        private const val TIMEOUT_APP_CODE = "PORTAL_POLL_TIMEOUT"
+    }
+}
+
+private fun String.isTerminalSuccess(): Boolean =
+    equals("succeeded", ignoreCase = true)
+
+private fun String.isTerminalFailure(): Boolean =
+    equals("failed", ignoreCase = true)
+
+private fun JobStatusResponseDto.toException(): PortalScrapingException {
+    val appCode = errorCode
+    val error = mapToPortalScrapingError(httpStatus = null, appCode = appCode)
+    return PortalScrapingException(
+        error = error,
+        httpStatus = null,
+        appCode = appCode,
+        retryable = retryable,
+        message = errorMessage ?: error.defaultMessage,
+    )
+}
+
+private fun JobSummaryResponseDto.toDomain(): ScrapingResult = ScrapingResult(
+    jobId = jobId,
+    studentInfo = studentInfo?.toDomain(),
+    status = status,
+    finishedAt = finishedAt,
+)
+
+private fun StudentInfoDto.toDomain(): StudentInfo = StudentInfo(
+    name = name,
+    school = school,
+    majorName = majorName,
+    studentCode = studentCode,
+    gradeLevel = gradeLevel,
+    status = status,
+    completedSemesterType = completedSemesterType,
+)

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

@@ -6,6 +6,7 @@ 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.LinkPortalUseCase
 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 +59,7 @@ val domainModule = module {
     // Academic use cases
     factory { GetAcademicSummaryUseCase(get()) }
     factory { GetAcademicRecordUseCase(get()) }
+
+    // Portal use cases
+    factory { LinkPortalUseCase(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,9 @@
+package com.chukchukhaksa.mobile.domain.portal.model
+
+class PortalScrapingException(
+    val error: PortalScrapingError,
+    val httpStatus: Int?,
+    val appCode: String?,
+    val retryable: Boolean? = null,
+    override val message: String = error.defaultMessage,
+) : RuntimeException(message)

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

@@ -0,0 +1,19 @@
+package com.chukchukhaksa.mobile.domain.portal.model
+
+sealed interface ScrapingProgress {
+    val jobId: String
+
+    data class Accepted(
+        override val jobId: String,
+    ) : ScrapingProgress
+
+    data class InProgress(
+        override val jobId: String,
+        val status: String,
+    ) : ScrapingProgress
+
+    data class Completed(
+        override val jobId: String,
+        val result: ScrapingResult,
+    ) : ScrapingProgress
+}

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

@@ -0,0 +1,18 @@
+package com.chukchukhaksa.mobile.domain.portal.model
+
+data class ScrapingResult(
+    val jobId: String?,
+    val studentInfo: StudentInfo?,
+    val status: String?,
+    val finishedAt: 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,13 @@
+package com.chukchukhaksa.mobile.domain.portal.repository
+
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingProgress
+import kotlinx.coroutines.flow.Flow
+
+interface PortalRepository {
+    fun linkPortal(
+        portalType: String,
+        username: String,
+        password: String,
+        idempotencyKey: String,
+    ): Flow<ScrapingProgress>
+}

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

@@ -0,0 +1,28 @@
+package com.chukchukhaksa.mobile.domain.portal.usecase
+
+import com.chukchukhaksa.mobile.domain.portal.model.ScrapingProgress
+import com.chukchukhaksa.mobile.domain.portal.repository.PortalRepository
+import kotlinx.coroutines.flow.Flow
+import kotlin.uuid.ExperimentalUuidApi
+import kotlin.uuid.Uuid
+
+class LinkPortalUseCase(
+    private val portalRepository: PortalRepository,
+) {
+    @OptIn(ExperimentalUuidApi::class)
+    operator fun invoke(
+        username: String,
+        password: String,
+        portalType: String = DEFAULT_PORTAL_TYPE,
+        idempotencyKey: String = Uuid.random().toString(),
+    ): Flow<ScrapingProgress> = portalRepository.linkPortal(
+        portalType = portalType,
+        username = username,
+        password = password,
+        idempotencyKey = idempotencyKey,
+    )
+
+    companion object {
+        const val DEFAULT_PORTAL_TYPE = "suwon"
+    }
+}