car-maintenance-system/android/QUICKSTART.md

车管家 Android 客户端 - 快速开始指南

项目概述

这是一个现代化的 Android 应用，为车管家 4S店车辆维保管理系统提供移动端支持。

开发前准备

1. 安装 Android Studio

下载并安装最新版本的 Android Studio: https://developer.android.com/studio

2. 配置 JDK

确保安装了 JDK 17 或更高版本：

java -version  # 应该显示 17.x.x 或更高

3. 启动后端服务

在运行 Android 应用之前，确保后端服务正在运行：

# 进入后端项目目录
cd car-maintenance-system/backend

# 使用 Maven 启动服务
mvn spring-boot:run

# 或者在 IDEA 中运行 SpringBootAppApplication.java

后端默认运行在 http://localhost:8080

4. 配置 API 地址

根据你的测试环境，修改 app/build.gradle.kts：

使用 Android 模拟器：

buildConfigField("String", "API_BASE_URL", "\"http://10.0.2.2:8080/api/\"")

使用真机：

buildConfigField("String", "API_BASE_URL", "\"http://YOUR_PC_IP:8080/api/\"")
// 例如: "http://192.168.1.100:8080/api/"

运行应用

方式一：使用 Android Studio

1. 打开 Android Studio
2. 选择 File > Open
3. 选择 car-maintenance-system/android 目录
4. 等待 Gradle 同步完成
5. 点击工具栏的 Run 按钮 (绿色三角形)

方式二：使用命令行

cd android

# 查看连接的设备
adb devices

# 安装并运行
./gradlew installDebug

测试账号

角色	用户名	密码	功能
管理员	admin	123456	系统管理、数据统计
工作人员	staff001	123456	工单处理、预约确认
客户	customer001	123456	查看车辆、预约服务

项目结构说明

android/
├── app/                           # 应用模块
│   ├── src/main/
│   │   ├── java/com/carmaintenance/
│   │   │   ├── data/              # 数据层
│   │   │   │   ├── local/         # 本地存储
│   │   │   │   ├── model/         # 数据模型
│   │   │   │   ├── remote/        # API接口
│   │   │   │   ├── repository/    # 数据仓库
│   │   │   │   └── manager/       # Token管理
│   │   │   ├── di/                # 依赖注入
│   │   │   ├── ui/                # UI层
│   │   │   │   ├── navigation/    # 导航
│   │   │   │   ├── screen/        # 页面
│   │   │   │   ├── theme/         # 主题
│   │   │   │   └── viewmodel/     # 视图模型
│   │   │   ├── CarMaintenanceApplication.kt
│   │   │   └── MainActivity.kt
│   │   └── res/                   # 资源文件
│   ├── build.gradle.kts           # 应用级构建配置
│   └── proguard-rules.pro         # 混淆规则
├── build.gradle.kts               # 项目级构建配置
├── settings.gradle.kts            # Gradle设置
└── gradle.properties              # Gradle属性

常见问题

1. Gradle 同步失败

问题: Gradle 同步时出现错误

解决方案:

# 清理项目
./gradlew clean

# 重新构建
./gradlew build

# 如果还是失败，删除 .gradle 目录后重试
rm -rf .gradle

2. 网络请求失败

问题: 应用无法连接到服务器

解决方案:

• 确认后端服务正在运行
• 检查 API_BASE_URL 配置
• 确保设备和电脑在同一网络（真机测试）
• 检查防火墙设置

3. 登录失败

问题: 登录时提示错误

解决方案:

• 确认后端数据库中有测试用户
• 检查用户名和密码是否正确
• 查看后端日志确认请求是否到达

4. 模拟器无法访问宿主机

问题: 模拟器中的 App 无法访问电脑上的后端服务

解决方案: 使用 10.0.2.2 代替 localhost:

// 错误
buildConfigField("String", "API_BASE_URL", "\"http://localhost:8080/api/\"")

// 正确（模拟器）
buildConfigField("String", "API_BASE_URL", "\"http://10.0.2.2:8080/api/\"")

5. 数据显示为空

问题: 登录后车辆、工单等数据显示为空

解决方案:

• 确认后端数据库有相关数据
• 使用 Admin 账号登录后台添加测试数据
• 检查客户ID是否正确关联

调试技巧

查看 API 请求

在 NetworkModule.kt 中，日志级别已设置为 BODY：

if (BuildConfig.DEBUG) {
    HttpLoggingInterceptor.Level.BODY
}

在 Logcat 中过滤 OkHttp 即可看到所有网络请求。

查看 Token 存储

在 Logcat 中过滤 TokenManager 可以看到 Token 相关的日志。

下一步开发

功能优先级

1. 高优先级

   • 在线预约表单
   • 车辆详情查看
   • 工单详情查看

2. 中优先级

   • 管理员完整功能
   • 工作人员功能
   • 推送通知

3. 低优先级

   • 数据刷新机制
   • 离线缓存
   • 图片上传

扩展功能建议

• 车辆照片上传
• 电子签名
• 扫码查看车辆
• 消息推送（Firebase）
• 支付集成
• 数据导出
• 多语言支持

技术支持

如有问题，请查看：

• Jetpack Compose 官方文档
• Hilt 官方文档
• Retrofit 官方文档