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

## 项目概述

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

## 开发前准备

### 1. 安装 Android Studio

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

### 2. 配置 JDK

确保安装了 JDK 17 或更高版本：
```bash
java -version  # 应该显示 17.x.x 或更高
```

### 3. 启动后端服务

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

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

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

# 或者在 IDEA 中运行 SpringBootAppApplication.java
```

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

### 4. 配置 API 地址

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

**使用 Android 模拟器：**
```kotlin
buildConfigField("String", "API_BASE_URL", "\"http://10.0.2.2:8080/api/\"")
```

**使用真机：**
```kotlin
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 按钮 (绿色三角形)

### 方式二：使用命令行

```bash
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 同步时出现错误

**解决方案**:
```bash
# 清理项目
./gradlew clean

# 重新构建
./gradlew build

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

### 2. 网络请求失败

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

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

### 3. 登录失败

**问题**: 登录时提示错误

**解决方案**:
- 确认后端数据库中有测试用户
- 检查用户名和密码是否正确
- 查看后端日志确认请求是否到达

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

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

**解决方案**:
使用 `10.0.2.2` 代替 `localhost`:
```kotlin
// 错误
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`：
```kotlin
if (BuildConfig.DEBUG) {
    HttpLoggingInterceptor.Level.BODY
}
```

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

### 查看 Token 存储

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

## 下一步开发

### 功能优先级

1. **高优先级**
   - 在线预约表单
   - 车辆详情查看
   - 工单详情查看

2. **中优先级**
   - 管理员完整功能
   - 工作人员功能
   - 推送通知

3. **低优先级**
   - 数据刷新机制
   - 离线缓存
   - 图片上传

### 扩展功能建议

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

## 技术支持

如有问题，请查看：
- [Jetpack Compose 官方文档](https://developer.android.com/jetpack/compose)
- [Hilt 官方文档](https://dagger.dev/hilt/)
- [Retrofit 官方文档](https://square.github.io/retrofit/)