pos-system/apps/app-client-base-swift/docs/vi/README.md

App Client Base Swift

Ứng dụng iOS native cho nền tảng GoodGo, xây dựng bằng Swift và SwiftUI theo kiến trúc MVVM.

📱 Tính Năng

Tính năng	Mô tả
🔐 Xác thực	Đăng nhập, Đăng ký, Quên mật khẩu với form validation
🏠 Trang chủ	Lời chào động, Items nổi bật, Feed hoạt động
🔍 Khám phá	Tìm kiếm địa điểm và dịch vụ
👤 Hồ sơ	Quản lý thông tin cá nhân và cài đặt
🌓 Chế độ tối	Hỗ trợ dark mode tự động
🌐 Đa ngôn ngữ	Hỗ trợ Tiếng Việt & Tiếng Anh

🛠️ Công Nghệ

Công nghệ	Phiên bản	Mục đích
Swift	5.9+	Ngôn ngữ chính
SwiftUI	iOS 15+	UI Framework declarative
Xcode	15.0+	IDE phát triển
URLSession	Native	HTTP networking
Keychain	Native	Lưu trữ token bảo mật
Combine	Native	Reactive programming

📋 Yêu Cầu

• macOS: 14.0+ (Sonoma)
• Xcode: 15.0+
• iOS Target: 15.0+
• Tài khoản Apple Developer: Cần thiết để deploy lên thiết bị

🚀 Bắt Đầu Nhanh

1. Clone và mở project

cd apps/app-client-base-swift
open AppClientBaseSwift/AppClientBaseSwift.xcodeproj

2. Chọn Simulator

• Menu Xcode: Product > Destination > iPhone 15 Pro (hoặc simulator khác)

3. Build và Run

# Sử dụng shortcut
⌘R (Command + R)

# Hoặc từ terminal
xcodebuild -project AppClientBaseSwift/AppClientBaseSwift.xcodeproj \
  -scheme AppClientBaseSwift \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
  build

4. Mock Login (để test)

Email: admin@goodgo.com
Password: 123456

📂 Cấu Trúc Project

AppClientBaseSwift/
├── App/
│   └── AppClientBaseSwiftApp.swift     # Entry point @main
│
├── Core/
│   ├── Constants/
│   │   └── Constants.swift              # API, App, Storage, DesignSystem
│   └── Extensions/
│       ├── View+Extensions.swift        # SwiftUI modifiers
│       └── String+Extensions.swift      # Validation, formatting
│
├── Models/
│   └── User.swift                       # Entity User + extensions
│
├── ViewModels/                          # MVVM ViewModels
│   ├── AuthViewModel.swift              # Login/Đăng ký/Quên mật khẩu
│   ├── HomeViewModel.swift              # Logic màn hình Home
│   └── ProfileViewModel.swift           # Quản lý hồ sơ
│
├── Views/
│   ├── Auth/                            # Màn hình xác thực
│   ├── Home/                            # Components trang chủ
│   └── Screens/                         # Màn hình chính
│
├── Services/
│   ├── APIService.swift                 # HTTP client với URLSession
│   └── AuthManager.swift                # Auth state + Keychain
│
└── Resources/
    ├── Assets.xcassets/                 # Hình ảnh & Màu sắc
    ├── en.lproj/                        # Bản địa hóa Tiếng Anh
    └── vi.lproj/                        # Bản địa hóa Tiếng Việt

🎨 Kiến Trúc

Pattern MVVM

┌─────────────────────────────────────────────────────────────┐
│                      VIEW (SwiftUI)                          │
│  HomeView, ProfileView, AuthContainerView, LoginView...     │
├─────────────────────────────────────────────────────────────┤
│                @StateObject / @EnvironmentObject             │
├─────────────────────────────────────────────────────────────┤
│                    VIEWMODEL (ObservableObject)              │
│  HomeViewModel, AuthViewModel, ProfileViewModel              │
│  • Thuộc tính @Published cho reactive UI                     │
│  • Phương thức async/await để tải dữ liệu                    │
├─────────────────────────────────────────────────────────────┤
│              Dependency Injection dựa trên Protocol          │
├─────────────────────────────────────────────────────────────┤
│                        SERVICES                              │
│  APIService (HTTP) • AuthManager (Auth State + Keychain)     │
└─────────────────────────────────────────────────────────────┘

📋 Quy Ước Code

Cấu trúc File

// MARK: - Imports
import SwiftUI

// MARK: - Định nghĩa Type
/// Mô tả bằng tiếng Việt
struct/class/enum TypeName {
    // MARK: - Properties
    // MARK: - Init
    // MARK: - Public Methods
    // MARK: - Private Methods
}

Pattern ViewModel

@MainActor
final class FeatureViewModel: ObservableObject {
    @Published var isLoading = false
    @Published var errorMessage: String?
    
    private let apiService: APIServiceProtocol
    
    init(apiService: APIServiceProtocol = APIService.shared) {
        self.apiService = apiService
    }
    
    func loadData() async {
        isLoading = true
        defer { isLoading = false }
        // ...
    }
}

⚙️ Cấu Hình

Cấu hình API

enum APIConfig {
    static let baseURL = "https://api.goodgo.vn"
    static let apiVersion = "/api/v1"
    static let timeout: TimeInterval = 30.0
}

🧪 Kiểm Thử

xcodebuild test \
  -project AppClientBaseSwift/AppClientBaseSwift.xcodeproj \
  -scheme AppClientBaseSwift \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro'

🔐 Bảo Mật

Tính năng	Triển khai
Lưu trữ Token	Keychain Services (không dùng UserDefaults)
Request bảo mật	Chỉ HTTPS, xác thực Bearer token
Quản lý Session	Tự động refresh token, logout an toàn
Bảo vệ dữ liệu	Mã hóa dữ liệu nhạy cảm khi lưu trữ

📱 Thiết Bị Hỗ Trợ

• iPhone: 8 trở lên (iOS 15+)
• iPad: Tất cả iPad với iOS 15+
• Hướng màn hình: Portrait (chính), Landscape (hỗ trợ)

🔗 Dự Án Liên Quan

• app-client-base-net - Client đa nền tảng .NET MAUI
• iam-service-net - Backend xác thực

📚 Tài Liệu Bổ Sung

• Hướng dẫn Kiến trúc - Chi tiết kiến trúc và quyết định thiết kế

📄 Giấy Phép

Bản quyền © 2026 GoodGo. Bảo lưu mọi quyền.