Add Android simulator and release packaging updates

Author: alvin000009238

.gitignore

@@ -46,6 +46,7 @@ shared_grades/
 !manifest.json
 *.md
 !README.md
+!AGENTS.md
 0_build_and_deploy.txt
 # Exclude specific JSONs but allow config templates if any
 
@@ -71,4 +72,4 @@ public/dist/
 
 # bat
 *.bat
-*.ps1
+*.ps1

AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+本檔給 AI agent 在此 repo 工作時使用。請先讀實際程式碼再改動，避免依照通用模板猜測架構。
+
+## 專案結構
+
+- `app/` 與 `server.py`：Flask 後端。`app.create_app()` 是主要 app factory，`server.py` 只負責本機啟動。
+- `frontend/`：Vite 前端原始碼，進入點是 `frontend/main.js`，樣式拆在 `frontend/styles/`。
+- `public/`：Flask 服務的靜態入口與 Vite build 輸出位置。
+- `android/`：獨立 Kotlin / Jetpack Compose / Material 3 Android app，package 為 `com.clhs.score`。
+- `tests/`：後端 pytest 與前端 Node 測試。
+
+## 工作規則
+
+- 優先保留既有資料流程與檔案分層。UI 改版請先找現有 screen、theme、chart 元件，不要另建平行 app。
+- 不要把帳密、token、cookie 或正式環境 secret 寫進程式碼或對話；使用 `.env`、local properties 或本機設定檔。
+- 此 repo 的 Markdown 預設會被 `.gitignore` 忽略；新增或更新 agent 文件後要確認 `AGENTS.md` 沒有被 ignore。
+- 文件預設使用繁體中文；程式碼註解只在能降低理解成本時加入。
+
+## 常用驗證
+
+- 後端：`pytest tests/backend/`
+- Python 語法：`python -m compileall app fetcher.py server.py`
+- 前端：`npm run test`、`npm run build`
+- Android：在 `android/` 內執行 `.\gradlew.bat test`
+
+在 Windows Codex 環境跑 Android Gradle 時，若 `java` 不在 PATH，使用 Android Studio 內建 JBR，並將 `GRADLE_USER_HOME`、`ANDROID_USER_HOME` 指到 workspace 內的暫存目錄。若測試一開始就出現 `could not open ...\jbr\lib\jvm.cfg`，通常是設定的 Android Studio JBR 路徑不存在或不完整；先用 `Test-Path` 或列出 `C:\Program Files\Android\Android Studio*` 確認實際 JBR 位置。本機曾遇到 `C:\Program Files\Android\Android Studio\jbr` 不可用，而 `C:\Program Files\Android\Android Studio1\jbr` 可用。

android/.gitignore

@@ -7,6 +7,7 @@ build/
 local.properties
 
 # Android generated artifacts
+app/release/
 *.apk
 *.ap_
 *.aab

android/app/build.gradle.kts

@@ -1,6 +1,7 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
 plugins {
     id("com.android.application")
-    id("org.jetbrains.kotlin.android")
     id("org.jetbrains.kotlin.plugin.compose")
 }
 
@@ -28,7 +29,21 @@ android {
     }
 
     kotlin {
-        jvmToolchain(17)
+        jvmToolchain(21)
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_17)
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+        }
     }
 
     testOptions {
@@ -44,7 +59,8 @@ dependencies {
 
     implementation("androidx.activity:activity-compose:1.13.0")
     implementation("androidx.compose.foundation:foundation")
-    implementation("androidx.compose.material:material-icons-extended")
+
+    implementation("androidx.compose.material:material-icons-core")
     implementation("androidx.compose.material3:material3")
     implementation("androidx.compose.runtime:runtime")
     implementation("androidx.compose.ui:ui")

android/app/proguard-rules.pro

@@ -0,0 +1,36 @@
+# ProGuard / R8 rules for SchoolGrades
+
+# OkHttp
+-dontwarn okhttp3.internal.platform.**
+-dontwarn org.bouncycastle.**
+-dontwarn org.conscrypt.**
+-dontwarn org.openjsse.**
+
+# Google Tink / security-crypto
+-dontwarn com.google.errorprone.annotations.**
+
+# kotlinx-serialization
+-keepattributes *Annotation*, InnerClasses
+-dontnote kotlinx.serialization.AnnotationsKt
+
+-keepclassmembers class kotlinx.serialization.json.** {
+    *** Companion;
+}
+-keepclasseswithmembers class kotlinx.serialization.json.** {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+
+-keep,includedescriptorclasses class com.clhs.score.**$$serializer { *; }
+-keepclassmembers class com.clhs.score.** {
+    *** Companion;
+}
+-keepclasseswithmembers class com.clhs.score.** {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+
+# Jsoup
+-keep class org.jsoup.** { *; }
+-dontwarn org.jsoup.**
+
+# Keep data classes used for JSON parsing
+-keep class com.clhs.score.data.** { *; }

android/app/src/androidTest/java/com/clhs/score/ui/ScoreUiTest.kt

@@ -114,6 +114,10 @@ class ScoreUiTest {
         composeRule.onNodeWithText("上一考比較").assertIsDisplayed()
         composeRule.onAllNodesWithText("班級平均").assertCountEquals(0)
         composeRule.onAllNodesWithText("校排").assertCountEquals(0)
+
+        composeRule.onNodeWithText("國語文").performScrollTo().performClick()
+        composeRule.waitForIdle()
+        composeRule.onAllNodesWithText("五標落點").assertCountEquals(0)
     }
 
     @Test
@@ -211,6 +215,7 @@ class ScoreUiTest {
                 val key = cleanSubjectName(subjectName)
                 expanded = if (key in expanded) expanded - key else expanded + key
             },
+            onOpenScoreSimulator = {},
         )
     }
 

android/app/src/main/ic_launcher-playstore.png

@@ -48,6 +48,40 @@ data class GradeTrend(
     val averageLine: String = points.joinToString(" → ") { "%.1f".format(it.weightedAverage) }
 }
 
+data class HistoryExamRef(
+    val yearTerm: YearTermOption,
+    val exam: ExamOption,
+) {
+    val yearValue: String = yearTerm.value
+    val examValue: String = exam.value
+    val examName: String = exam.text
+}
+
+data class SimulationHistorySource(
+    val yearTerm: YearTermOption,
+    val exams: List<ExamOption>,
+    val usesPreviousTerm: Boolean,
+    val examRefs: List<HistoryExamRef>? = null,
+) {
+    val historyExams: List<HistoryExamRef> = examRefs ?: exams.map { HistoryExamRef(yearTerm, it) }
+
+    val label: String = if (usesPreviousTerm) {
+        "近 ${historyExams.size} 次段考"
+    } else {
+        "同學期前 ${exams.size} 次考試"
+    }
+}
+
+data class ScoreSimulationResult(
+    val adjustedAverage: Double,
+    val projectedAverage: Double,
+    val trendDelta: Double,
+    val estimatedClassRank: Int?,
+    val classCount: Int?,
+    val historyCount: Int,
+    val hasRankProjection: Boolean,
+)
+
 data class RankProjection(
     val subjectName: String,
     val suggestedIncrease: Double,
@@ -258,6 +292,55 @@ fun YearTermOption.previousExamsOf(examValue: String?, limit: Int = 2): List<Exa
     return exams.subList(max(0, index - limit), index)
 }
 
+fun List<YearTermOption>.sameTermHistorySource(
+    yearValue: String?,
+    examValue: String?,
+): SimulationHistorySource? {
+    if (yearValue.isNullOrBlank()) return null
+    val current = firstOrNull { it.value == yearValue } ?: return null
+    val sameTermExams = current.previousExamsOf(examValue, limit = Int.MAX_VALUE)
+    if (sameTermExams.isEmpty()) return null
+    return SimulationHistorySource(
+        yearTerm = current,
+        exams = sameTermExams,
+        usesPreviousTerm = false,
+    )
+}
+
+fun List<YearTermOption>.simulationHistorySource(
+    yearValue: String?,
+    examValue: String?,
+): SimulationHistorySource? {
+    if (yearValue.isNullOrBlank() || examValue.isNullOrBlank()) return null
+    val orderedExams = sortedWith(
+        compareBy<YearTermOption>({ it.sortKey().first }, { it.sortKey().second }),
+    ).flatMap { yearTerm ->
+        yearTerm.exams.map { exam -> HistoryExamRef(yearTerm, exam) }
+    }
+    val currentIndex = orderedExams.indexOfFirst {
+        it.yearValue == yearValue && it.examValue == examValue
+    }
+    if (currentIndex <= 0) return null
+    val historyExams = orderedExams.subList(max(0, currentIndex - 3), currentIndex)
+    if (historyExams.isEmpty()) return null
+    return SimulationHistorySource(
+        yearTerm = historyExams.first().yearTerm,
+        exams = historyExams.map { it.exam },
+        usesPreviousTerm = historyExams.any { it.yearValue != yearValue },
+        examRefs = historyExams,
+    )
+}
+
+fun List<YearTermOption>.latestYearTerm(): YearTermOption? =
+    maxWithOrNull(
+        compareBy<YearTermOption>(
+            { option -> parseYearTerm(option.value, defaultYear = "0", defaultTerm = "0").first.toIntOrNull() ?: 0 },
+            { option -> parseYearTerm(option.value, defaultYear = "0", defaultTerm = "0").second.toIntOrNull() ?: 0 },
+        ),
+    )
+
+fun YearTermOption.latestExam(): ExamOption? = exams.lastOrNull()
+
 fun buildGradeTrend(
     currentExamName: String,
     currentReport: GradeReport,
@@ -269,6 +352,46 @@ fun buildGradeTrend(
     return GradeTrend(points = previousPoints + currentReport.toTrendPoint(currentExamName))
 }
 
+fun simulateScores(
+    currentReport: GradeReport,
+    historyReports: List<GradeReport>,
+    adjustedScores: Map<String, Double>,
+): ScoreSimulationResult {
+    val adjustedAverage = weightedAverageFor(currentReport.subjects, adjustedScores)
+    val historyPoints = historyReports + currentReport
+    val trendDelta = historyPoints
+        .zipWithNext { previous, next -> next.weightedAverage() - previous.weightedAverage() }
+        .takeIf { it.isNotEmpty() }
+        ?.average()
+        ?: 0.0
+    val projectedAverage = (adjustedAverage + trendDelta).coerceIn(0.0, 100.0)
+    val currentRank = currentReport.examSummary?.classRank?.toInt()
+    val classCount = currentReport.examSummary?.classCount
+    val estimatedRank = if (!hasAdjustedScores(currentReport, adjustedScores)) {
+        currentRank?.let { rank ->
+            if (classCount != null && classCount > 0) rank.coerceIn(1, classCount) else rank
+        }
+    } else if (classCount != null && classCount > 0) {
+        relativeRegressionRank(
+            historyReports = historyReports,
+            currentReport = currentReport,
+            adjustedScores = adjustedScores,
+            classCount = classCount,
+        )
+    } else {
+        null
+    }
+    return ScoreSimulationResult(
+        adjustedAverage = adjustedAverage,
+        projectedAverage = projectedAverage,
+        trendDelta = trendDelta,
+        estimatedClassRank = estimatedRank,
+        classCount = classCount,
+        historyCount = historyReports.size,
+        hasRankProjection = estimatedRank != null,
+    )
+}
+
 fun deltaText(label: String, delta: Double, unit: String = ""): String {
     val direction = when {
         delta > 0.05 -> "+"
@@ -289,6 +412,93 @@ private fun rankDelta(current: Double?, previous: Double?): Int? {
     return previous.toInt() - current.toInt()
 }
 
+private fun YearTermOption.sortKey(): Pair<Int, Int> {
+    val (year, term) = parseYearTerm(value, defaultYear = "0", defaultTerm = "0")
+    return (year.toIntOrNull() ?: 0) to (term.toIntOrNull() ?: 0)
+}
+
+private fun weightedAverageFor(
+    subjects: List<SubjectScore>,
+    adjustedScores: Map<String, Double>,
+): Double {
+    val totalWeight = subjects.sumOf { subjectWeight(it.subjectName) }
+    if (totalWeight <= 0) return 0.0
+    val weightedTotal = subjects.sumOf { subject ->
+        val score = adjustedScores[cleanSubjectName(subject.subjectName)] ?: subject.scoreValue
+        score.coerceIn(0.0, 100.0) * subjectWeight(subject.subjectName)
+    }
+    return weightedTotal / totalWeight
+}
+
+private fun hasAdjustedScores(
+    report: GradeReport,
+    adjustedScores: Map<String, Double>,
+): Boolean = report.subjects.any { subject ->
+    val adjusted = adjustedScores[cleanSubjectName(subject.subjectName)] ?: subject.scoreValue
+    abs(adjusted - subject.scoreValue) > 0.05
+}
+
+private fun relativeRegressionRank(
+    historyReports: List<GradeReport>,
+    currentReport: GradeReport,
+    adjustedScores: Map<String, Double>,
+    classCount: Int,
+): Int? {
+    val points = historyReports.mapNotNull { report ->
+        val rank = report.examSummary?.classRank ?: return@mapNotNull null
+        val relativeScore = report.examRelativeScore() ?: return@mapNotNull null
+        relativeScore to rank
+    }
+    if (points.size < 3) return null
+    val adjustedRelativeScore = currentReport.examRelativeScore(adjustedScores) ?: return null
+    val relativeMean = points.map { it.first }.average()
+    val rankMean = points.map { it.second }.average()
+    val denominator = points.sumOf { (relativeScore, _) ->
+        val delta = relativeScore - relativeMean
+        delta * delta
+    }
+    if (denominator <= 0.0001) return null
+    val slope = points.sumOf { (relativeScore, rank) ->
+        (relativeScore - relativeMean) * (rank - rankMean)
+    } / denominator
+    val intercept = rankMean - slope * relativeMean
+    return (slope * adjustedRelativeScore + intercept)
+        .roundToInt()
+        .coerceIn(1, classCount)
+}
+
+private fun GradeReport.examRelativeScore(
+    adjustedScores: Map<String, Double> = emptyMap(),
+): Double? {
+    var weightedTotal = 0.0
+    var totalWeight = 0
+    subjects.forEachIndexed { index, subject ->
+        val standard = standardFor(subject, index) ?: return@forEachIndexed
+        val classAverage = subject.classAverageOrNull() ?: return@forEachIndexed
+        val spread = standard.relativeSpread() ?: return@forEachIndexed
+        val score = adjustedScores[cleanSubjectName(subject.subjectName)] ?: subject.scoreValue
+        val weight = subjectWeight(subject.subjectName)
+        weightedTotal += ((score.coerceIn(0.0, 100.0) - classAverage) / spread) * weight
+        totalWeight += weight
+    }
+    if (totalWeight <= 0) return null
+    return weightedTotal / totalWeight
+}
+
+private fun SubjectScore.classAverageOrNull(): Double? =
+    classAverageDisplay.toDoubleOrNull() ?: classAverage
+
+private fun GradeStandard.relativeSpread(): Double? {
+    val topBottom = top?.let { topValue ->
+        bottom?.let { bottomValue -> topValue - bottomValue }
+    }
+    if (topBottom != null && topBottom > 0.0) return topBottom
+    val frontBack = front?.let { frontValue ->
+        back?.let { backValue -> frontValue - backValue }
+    }
+    return frontBack?.takeIf { it > 0.0 }
+}
+
 private fun GradeReport.toTrendPoint(examName: String): GradeTrendPoint = GradeTrendPoint(
     examName = examName.ifBlank { examSummary?.examName.orEmpty().ifBlank { "考試" } },
     weightedAverage = weightedAverage(),