# Clone Repo và Mở Project KMP Lần Đầu

> Mở project Kotlin Multiplatform production thật thay vì một toy starter project.

- URL: https://dantech.academy/courses/kotlin-accelerator/engineer-builder/00-setup-app-running/lesson-02-clone-repo-open-project
- Khóa học: [Mobile Action Pro](https://dantech.academy/courses/kotlin-accelerator.md)
- Module: Setup App Chạy Được
- Thời lượng: 12 phút
- Độ khó: beginner
- Truy cập: Miễn phí, đọc toàn bài
- English: https://dantech.academy/en/courses/kotlin-accelerator/engineer-builder/00-setup-app-running/lesson-02-clone-repo-open-project.md

## Mục tiêu

- Xác thực GitHub access bằng GitHub CLI và clone private course repository
- Mở đúng repository root trong Android Studio thay vì một nested module folder
- Hiểu Gradle sync đầu tiên làm gì với project KMP và phân loại error đầu tiên khi sync fail

---

## Mục Tiêu Bài Học

Sau bài này bạn có:

- GitHub account đã access được private course repository,
- Course codebase đã clone vào một workspace cố định,
- Android Studio đang mở đúng project root,
- Hiểu Gradle sync đầu tiên làm gì với một project Kotlin Multiplatform.

## Trước Khi Clone

Cần đảm bảo ba điều:

- GitHub access: bạn có account và thấy private repository.
- Git authentication: máy của bạn clone được code từ GitHub.
- Project root: Android Studio mở đúng root folder của repo.

Tài liệu official:

- [Tạo tài khoản GitHub](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github)
- [GitHub CLI](https://cli.github.com/)

## Phần 1: Xác Nhận GitHub Access Trong Browser

Mở link course invite trong browser trước và kiểm tra:

1. Bạn đăng nhập đúng GitHub account đã dùng khi mua khóa học.
2. Repository page mở được, không trả về `404`.
3. Bạn thấy nút xanh `Code` hoặc clone URL.

## Phần 2: Chọn Cách Authenticate

| Cách  | Khi nào dùng                                                       | Ví dụ                             |
| ----- | ------------------------------------------------------------------ | --------------------------------- |
| HTTPS | Default đơn giản; hợp với GitHub CLI hoặc credential manager login | `https://github.com/org/repo.git` |
| SSH   | Hợp nếu bạn đã quen SSH keys và biết cách debug key problems       | `git@github.com:org/repo.git`     |

Cài [GitHub CLI](https://cli.github.com/) để khỏi phải copy-paste personal access token vào terminal. Sau đó chạy:

```bash
gh --version
gh auth login
gh auth status
```

Làm theo browser login flow. Khi `gh auth status` báo bạn đã login đúng account, máy đã có đường authenticate sạch.

Đừng paste personal access token vào notes, screenshots, Discord, support messages hoặc shell history.

## Phần 3: Tạo Workspace Cố Định

Đặt repo ở một nơi bạn sẽ giữ suốt khóa học, không phải folder download ngẫu nhiên:

```bash
mkdir -p ~/Desktop/kotlin/dan-tech-academy
cd ~/Desktop/kotlin/dan-tech-academy
git clone <course-repo-url>
```

Dùng đúng private repository URL mà bạn được cấp quyền. Nếu clone báo `Repository not found`, kiểm tra lại browser access. Nếu clone cứ hỏi authentication, hoàn tất `gh auth login` hoặc credential manager rồi thử lại.

## Phần 4: Mở Đúng Root Folder

Repo có nhiều folder và nhiều module. Bạn phải mở repository root, không mở `app`, `feature`, `core`, `shared-app` hay `iosApp`.

Root folder có các file như:

```text
settings.gradle.kts
build.gradle.kts
gradlew
```

Không thấy `settings.gradle.kts` nghĩa là bạn đang ở sai folder. Mở Android Studio, chọn `Open`, chọn repo root và để IDE import Gradle project. Chỉ root folder mới cho Gradle biết toàn bộ danh sách module.

Folder `iosApp/` chứa Xcode project. Android Studio không dùng nó. Nếu bạn có Mac, đây là project bạn mở bằng Xcode để chạy bản iOS.

## Phần 5: Để Gradle Sync Chạy Xong

Tài liệu official: [Gradle build lifecycle](https://docs.gradle.org/current/userguide/build_lifecycle.html).

Sync đầu tiên chậm vì Gradle dựng model của project:

- Đọc `settings.gradle.kts` để biết các module được include.
- Build `build-logic/`, nơi chứa convention plugin dùng chung cho mọi module.
- Đọc build file của từng module.
- Tải Gradle wrapper, plugins và library dependencies (Kotlin Multiplatform, Android Gradle Plugin, Compose Multiplatform, Koin, Ktor...).
- Dựng index để Android Studio hiểu code trong `commonMain`, `androidMain` và `iosMain`.

Đừng cancel sync chỉ vì progress bar đứng yên. Chờ tới khi có success rõ ràng hoặc error đầu tiên rõ ràng. Stack trace dài thường chỉ có một nguyên nhân thật, nằm gần phía trên.

## Định Hướng Nhanh

Bạn chỉ cần bản đồ thô lúc này để biết mỗi folder chứa gì.

| Khu vực         | Cách hiểu cho người mới                                       |
| --------------- | ------------------------------------------------------------- |
| `app`           | Android entry point                                           |
| `iosApp`        | Xcode project, iOS entry point (không phải Gradle module)     |
| `shared-app`    | Phần app dùng chung cho cả hai nền tảng: khởi động, navigation |
| `feature`       | Screens và user flows                                         |
| `domain`        | Use cases và business rules                                   |
| `data`          | Repository implementations và external services               |
| `core`, `kernel`| Shared technical foundations                                  |
| `theme`         | Design system styling                                         |
| `ui-components` | UI building blocks dùng lại                                   |

## Bảng Xử Lý Lỗi

| Dạng lỗi                                                 | Kiểm tra trước                                                       |
| -------------------------------------------------------- | -------------------------------------------------------------------- |
| Repository page trả về `404`                             | Sai GitHub account hoặc chưa accept invite                           |
| `Repository not found` khi clone                         | Browser access và clone URL                                          |
| Authentication cứ hỏi lại                                | `gh auth status` hoặc Git credential manager                         |
| Android Studio không có Gradle task                      | Bạn mở nested folder thay vì repo root                               |
| Không tìm thấy SDK                                       | Mở SDK Manager và xác nhận SDK location                              |
| Gradle không tải được dependencies                       | Network, proxy, VPN hoặc repo access                                 |
| `Cannot find a Java installation ... languageVersion=17` | Máy chưa có JDK 17. Cài JDK 17 và đặt `JAVA_HOME` trỏ vào nó        |
| Plugin version error                                     | Cập nhật Android Studio stable mới nhất (repo dùng AGP 9)            |
| Thiếu `google-services.json`                             | Cần tải file này từ Firebase Console vào `app/` rồi mới build app đầy đủ |

## Checkpoint

```bash
git status
```

Bạn hoàn tất bài này khi:

- Android Studio đang mở repository root.
- Gradle sync thành công. Nếu sync fail, bạn đã copy được error đầu tiên và phân loại nó: access, SDK, JDK, network, dependency hay thiếu local config.

---

- Bài trước: [Cài đặt Git, JDK 17, Android Studio và SDK](https://dantech.academy/courses/kotlin-accelerator/engineer-builder/00-setup-app-running/lesson-01-install-android-studio-sdk.md)
- Bài tiếp theo: [Checklist Tài Khoản Dịch Vụ](https://dantech.academy/courses/kotlin-accelerator/engineer-builder/00-setup-app-running/lesson-03-service-account-checklist.md)