舞萌查分系统-maimaiCheck

1. 立项背景和目标
背景：舞萌DX官方无成绩查询系统，现有网页查分器操作繁琐、体验不佳。
目标：开发原生Android查分器，让玩家快速查询成绩，清晰展示Rating和Best 50数据。
2. 核心功能模块
模块 功能
玩家查询 输入玩家名，调用水鱼API获取数据
状态管理 管理空闲/加载/成功/错误四种UI状态
信息展示 展示玩家Rating、额外Rating
成绩列表 展示DX/SD谱面Best 50，含评级、达成率、定数等
错误处理 网络异常、玩家不存在等友好提示
3. 业务流程
text
启动 → 输入玩家名 → 点击查询
↓
加载中...
↓
├─ 成功 → 显示玩家信息 + 成绩列表
└─ 失败 → 显示错误提示 → 重新查询

1. 整体架构和设计思路
采用 MVVM架构，分为三层：
View层：Jetpack Compose + Material 3，负责UI渲染和用户交互
ViewModel层：AndroidX ViewModel + 协程，负责状态管理和业务逻辑
网络层：Retrofit + Gson，负责API调用和JSON解析
使用密封类定义空闲、加载中、成功、错误四种UI状态，实现单向数据流。成绩列表使用LazyColumn懒加载优化性能。
2.我的负责模块和结果
本人独立完成全部开发工作：
数据模型：定义PlayerData、Charts、ScoreRecord三个数据类，覆盖14个字段
网络请求：配置Retrofit客户端，实现API接口，设置30秒超时
状态管理：实现UiState密封类和ViewModel，管理四种状态切换
UI构建：开发搜索框、玩家卡片、成绩列表、加载动画、错误提示等6个界面组件
错误处理：封装HTTP异常、网络断开、超时等5种错误类型的统一处理
单元测试：编写4个测试用例，全部通过
项目成果：完成功能完整的Android查分器，代码约400行，运行稳定。
3.我遇到的难点和解决方案
协程测试失败：在编写单元测试时，网络请求是异步执行的，断言执行时协程还未完成，导致测试总是失败。解决方案是使用协程测试库中的 runTest 配合 advanceUntilIdle 方法，等待所有协程执行完毕后再进行断言，确保测试结果正确。
@Composable注解编译错误：定义颜色函数时内部使用了 MaterialTheme，但函数本身未标记 @Composable 注解，导致编译报错。考虑到这些函数只需要返回固定颜色值，不需要依赖Compose上下文，因此将函数改为普通函数，直接返回十六进制颜色值，问题解决。

HTTP 400错误排查：查询玩家名时始终返回400错误，最初以为是代码问题，排查了请求头、请求体格式等多个方面。后来发现是因为该玩家名未在水鱼查分器官网绑定账号，API返回的400实际上是“玩家不存在”的含义。解决方案是在错误处理中增加对400状态码的特殊处理，给出“未找到玩家，请确认玩家名是否正确或是否已绑定”的友好提示。
包名不一致导致编译失败：测试文件和主代码文件的包名不一致，导致编译时找不到相关类。解决方案是统一所有文件的包名为 com.example.mamaicheck，确保代码能够正确引用。
成绩列表滚动卡顿：最初使用Column垂直排列所有成绩条目，当成绩数量较多时界面滚动出现明显卡顿。改用LazyColumn懒加载列表后，只渲染可见区域的条目，滚动流畅度大幅提升。