@leejungkiin/awkit 1.0.6 → 1.0.8

package/skills/smali-to-kotlin/phase-1-architecture.md

@@ -0,0 +1,166 @@
+# 🏗️ Phase 1: Architecture (District View)
+
+> **Zoom Level:** 1 — Architecture Design
+> **Goal:** Design the overall architecture BEFORE writing any code.
+> **Input:** Completed App Map from Phase 0.
+> **Output:** Architecture Blueprint (layer maps, feature tables, API list). **NO CODE BODIES.**
+
+---
+
+## ⛔ OUTPUT RULE
+
+```
+✅ ALLOWED: Architecture diagrams, layer maps, feature-to-file mapping tables, API endpoint tables
+✅ ALLOWED: File paths, package names, dependency lists
+❌ BLOCKED: Function bodies, implementation details, actual Kotlin code
+⚠️ EXCEPTION: build.gradle.kts skeleton (plugin + dependency declarations only)
+```
+
+---
+
+## 📋 Sub-steps
+
+### 1.1: Layer Design
+
+Design Clean Architecture layers based on App Map:
+
+```
+┌─────────────────────────────────────┐
+│ Presentation                        │
+│ ├── screens/ ([N] screens)          │
+│ ├── navigation/ (NavGraph)          │
+│ └── theme/ (Material3)             │
+├─────────────────────────────────────┤
+│ Domain                              │
+│ ├── model/ ([N] business models)    │
+│ ├── repository/ ([N] interfaces)   │
+│ └── usecase/ ([N] use cases)        │
+├─────────────────────────────────────┤
+│ Data                                │
+│ ├── remote/ ([N] API services)     │
+│ ├── local/ (Room, DataStore)       │
+│ └── repository/ (implementations)  │
+├─────────────────────────────────────┤
+│ DI                                  │
+│ └── modules/ (Network, DB, Repo)   │
+└─────────────────────────────────────┘
+```
+
+### 1.2: Feature → File Mapping
+
+Map each feature to its Clean Architecture components:
+
+| Feature | Domain Model | Repository | UseCase | Screen | ViewModel |
+|---------|-------------|-----------|---------|--------|-----------|
+| Auth | User, Token | AuthRepo | LoginUC | Login | AuthVM |
+| Home | Data | HomeRepo | GetDataUC | Home | HomeVM |
+| ... | ... | ... | ... | ... | ... |
+
+### 1.3: API Endpoint Inventory
+
+Extract ALL API endpoints from Smali analysis:
+
+| # | Method | Endpoint | Auth | Request | Response | Notes |
+|---|--------|----------|------|---------|----------|-------|
+| 1 | POST | /auth/login | No | email, pwd | JWT token | - |
+| 2 | GET | /users/me | Bearer | - | User object | - |
+
+**How to find in Smali:**
+```
+Look for: const-string → "https://" or "http://"
+Look for: .field → BASE_URL, API_URL
+Look for: StringBuilder + append patterns (endpoint construction)
+Look for: annotation patterns (@GET, @POST in okhttp/retrofit)
+```
+
+### 1.4: Data Schema Inventory
+
+List ALL data structures found:
+
+| Model | Fields (key ones) | Source | Storage |
+|-------|-------------------|--------|---------|
+| User | id, name, email, avatar | API | Room + Memory |
+| Settings | theme, language, notifications | Local | DataStore |
+
+### 1.5: Project Structure
+
+Propose directory structure based on features:
+
+```
+app/src/main/java/com/package/
+├── App.kt
+├── di/ (AppModule, NetworkModule, DatabaseModule)
+├── data/
+│   ├── remote/api/ ([N] Retrofit interfaces)
+│   ├── remote/dto/ (DTOs)
+│   ├── local/db/ (Room)
+│   ├── local/datastore/ (DataStore)
+│   └── repository/ (Implementations)
+├── domain/
+│   ├── model/ (Business models)
+│   ├── repository/ (Interfaces)
+│   └── usecase/ (Use cases)
+├── presentation/
+│   ├── navigation/ (NavGraph, Routes)
+│   ├── theme/ (Colors, Typography, Theme)
+│   ├── components/ (Shared composables)
+│   └── screens/
+│       ├── splash/
+│       ├── auth/
+│       ├── home/
+│       └── [feature]/
+└── util/ (Extensions, helpers)
+```
+
+### 1.6: Build Order Suggestion
+
+Recommend order based on dependency graph:
+
+```
+1. 🟢 Project setup + DI skeleton + Theme
+2. 🟢 Domain models (data classes — no logic)
+3. 🟡 Data layer (API interfaces + Room entities)
+4. 🟡 Core utils (crypto, formatters — need parity testing)
+5. 🔴 UI screens (per-feature, starting from auth)
+6. 🔴 SDK integration + Parity check
+```
+
+### 1.7: Tech Stack Decisions
+
+Confirm decisions from Phase 0 Library Report:
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Image Loading | Coil (replace Glide) | Modern, Compose-native |
+| JSON | Kotlin Serialization | Type-safe, no reflection |
+| ... | ... | ... |
+
+---
+
+## 📊 Output: Architecture Blueprint
+
+Use template from `templates/architecture.md`. Must include:
+
+1. **Layer Map** — ASCII architecture diagram with counts
+2. **Feature Table** — feature → file mapping
+3. **API Inventory** — all endpoints found
+4. **Data Schema** — all models with key fields
+5. **Project Structure** — proposed directory tree
+6. **Build Order** — suggested implementation sequence
+7. **Tech Decisions** — confirmed choices
+
+---
+
+## ✅ Gate
+
+```
+"🏗️ Architecture Blueprint xong. Anh muốn bắt đầu từ feature nào?
+Em suggest: [Feature X] vì [reason — e.g., nhiều feature khác phụ thuộc]."
+
+→ User picks feature → Proceed to Phase 2 (Blueprint) for that feature
+→ User wants changes → Adjust architecture
+```
+
+---
+
+*Phase 1: Architecture — Design before you build*

package/skills/smali-to-kotlin/phase-2-blueprint-ui.md

@@ -0,0 +1,347 @@
+# 📐 Phase 2: Blueprint + UI Design (Per Feature) — Android
+
+> **Zoom Level:** 2 — Feature Detail
+> **Goal:** Design contracts AND code UI visual shell for ONE feature.
+> **Input:** Architecture Blueprint (Phase 1) + user's chosen feature.
+> **Output:** Approved contracts + Working UI shell with mock data.
+
+---
+
+## ⛔ OUTPUT RULE
+
+```
+PART A — Contracts (signatures only):
+  ✅ Interface signatures, data class definitions, sealed classes
+  ✅ Retrofit interface with @GET/@POST annotations (no body)
+  ✅ UiState sealed class, Event sealed class, Action sealed class
+  ❌ Function body implementations (use TODO())
+
+PART B — UI (visual code):
+  ✅ Full Jetpack Compose code for screen
+  ✅ Hardcoded mock data (using UiState from Part A)
+  ✅ Real resources (icons, colors, images extracted in 2.7)
+  ✅ @Preview for ALL states (normal, loading, error, empty)
+  ❌ Real ViewModel connection — use parameter defaults
+  ❌ Real API calls
+  ❌ Business logic
+```
+
+---
+
+## 📋 Sub-steps
+
+### 2.1: Deep Smali Reading
+
+Read Smali/Java files for the chosen feature.
+
+**What to extract:**
+- Class hierarchy (extends, implements)
+- Field declarations → model properties
+- Method signatures → API contracts
+- String constants → URLs, keys, messages
+- Control flow → business rules (document, don't code)
+
+**Smali Quick Ref:**
+```
+.field → class fields (properties)
+.method → method start
+.end method → method end
+invoke-virtual → instance method call
+invoke-static → static method call
+const-string → string literal
+new-instance → object creation
+if-eqz/if-nez → conditional branches
+```
+
+See `smali-reading-guide.md` for comprehensive guide.
+
+### 2.2: Domain Model Contracts
+
+```kotlin
+// Domain model
+data class User(
+    val id: String,
+    val fullName: String,
+    val email: String,
+    val avatarUrl: String?,
+    val isVerified: Boolean
+)
+
+// DTO (from API)
+@Serializable
+data class UserDto(
+    @SerialName("user_id") val userId: String,
+    @SerialName("full_name") val fullName: String,
+    @SerialName("email") val email: String,
+    @SerialName("avatar_url") val avatarUrl: String?,
+    @SerialName("is_verified") val isVerified: Boolean
+)
+```
+
+### 2.3: Repository Contract
+
+```kotlin
+interface AuthRepository {
+    suspend fun login(email: String, password: String): Result<User>
+    suspend fun register(name: String, email: String, password: String): Result<User>
+    suspend fun logout()
+    fun isLoggedIn(): Flow<Boolean>
+    fun getCurrentUser(): Flow<User?>
+}
+```
+
+### 2.4: API Contract
+
+```kotlin
+interface AuthApi {
+    @POST("auth/login")
+    suspend fun login(@Body request: LoginRequest): LoginResponse
+
+    @POST("auth/register")
+    suspend fun register(@Body request: RegisterRequest): RegisterResponse
+
+    @GET("auth/me")
+    suspend fun getCurrentUser(@Header("Authorization") token: String): UserDto
+}
+```
+
+### 2.5: UseCase Signatures
+
+```kotlin
+class LoginUseCase(private val authRepo: AuthRepository) {
+    suspend operator fun invoke(email: String, password: String): Result<User>
+    // Implementation: TODO()
+}
+```
+
+### 2.6: UI State Design
+
+```kotlin
+// State
+data class LoginUiState(
+    val email: String = "",
+    val password: String = "",
+    val isLoading: Boolean = false,
+    val error: String? = null,
+    val isPasswordVisible: Boolean = false
+)
+
+// Events (one-time actions)
+sealed interface LoginEvent {
+    data class NavigateToHome(val user: User) : LoginEvent
+    data class ShowSnackbar(val message: String) : LoginEvent
+}
+
+// Actions (user interactions)
+sealed interface LoginAction {
+    data class UpdateEmail(val email: String) : LoginAction
+    data class UpdatePassword(val password: String) : LoginAction
+    data object TogglePasswordVisibility : LoginAction
+    data object Submit : LoginAction
+}
+```
+
+### 2.7: Resource Extraction ⭐ (Before UI code!)
+
+> **Why here?** UI code (2.8) needs real assets. If resources come later, UI will be full of placeholders — defeating the purpose of visual parity.
+
+**Process:**
+1. Analyze layout XML to list needed resources:
+   ```bash
+   grep -o '@drawable/[a-z_]*' [apktool]/res/layout/activity_login.xml | sort -u
+   grep -o '@color/[a-z_]*' [apktool]/res/layout/activity_login.xml | sort -u
+   grep 'const-string' [apktool]/smali/.../LoginActivity.smali | grep -i string
+   ```
+2. Copy ONLY needed resources to new project
+3. Verify all resources compile
+
+**Output:**
+```markdown
+### 📦 Resources for [Screen]
+- Drawables: [list]
+- Colors: [list]
+- Strings: [list]
+- Dimens: [list]
+✅ All accessible
+```
+
+### 2.8: UI Implementation — Visual Shell ⭐
+
+> **Goal:** Code the screen with HARDCODED mock data. Pixel-perfect visual parity with original app.
+
+**Rules:**
+```
+✅ MUST DO:
+  - Use UiState from 2.6 (hardcode sample values as defaults)
+  - Use REAL resources extracted in 2.7
+  - Display ALL visual elements from original app
+  - Match: spacing, font size, colors, icon placement
+  - Code ALL states: normal, loading, error, empty
+  - Create @Preview for each state
+
+❌ MUST NOT:
+  - Connect real ViewModel (use parameter defaults)
+  - Call real APIs
+  - Code business logic
+  - Use DI/injection
+```
+
+**Pattern — Stateless Composable:**
+```kotlin
+@Composable
+fun LoginScreenContent(
+    uiState: LoginUiState = LoginUiState(),  // Hardcoded default
+    onAction: (LoginAction) -> Unit = {}      // No-op default
+) {
+    Scaffold { padding ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(padding)
+                .padding(24.dp),
+            horizontalAlignment = Alignment.CenterHorizontally
+        ) {
+            // Logo — real resource from 2.7
+            Image(
+                painter = painterResource(R.drawable.app_logo),
+                contentDescription = null,
+                modifier = Modifier.size(120.dp)
+            )
+            Spacer(Modifier.height(48.dp))
+
+            // Email
+            OutlinedTextField(
+                value = uiState.email,
+                onValueChange = { onAction(LoginAction.UpdateEmail(it)) },
+                label = { Text("Email") },
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email),
+                modifier = Modifier.fillMaxWidth()
+            )
+            Spacer(Modifier.height(16.dp))
+
+            // Password with toggle
+            OutlinedTextField(
+                value = uiState.password,
+                onValueChange = { onAction(LoginAction.UpdatePassword(it)) },
+                label = { Text("Password") },
+                visualTransformation = if (uiState.isPasswordVisible)
+                    VisualTransformation.None else PasswordVisualTransformation(),
+                trailingIcon = {
+                    IconButton(onClick = { onAction(LoginAction.TogglePasswordVisibility) }) {
+                        Icon(
+                            imageVector = if (uiState.isPasswordVisible)
+                                Icons.Default.VisibilityOff else Icons.Default.Visibility,
+                            contentDescription = "Toggle password"
+                        )
+                    }
+                },
+                modifier = Modifier.fillMaxWidth()
+            )
+            Spacer(Modifier.height(32.dp))
+
+            // Login Button
+            Button(
+                onClick = { onAction(LoginAction.Submit) },
+                enabled = !uiState.isLoading,
+                modifier = Modifier.fillMaxWidth().height(50.dp)
+            ) {
+                if (uiState.isLoading) {
+                    CircularProgressIndicator(
+                        modifier = Modifier.size(24.dp),
+                        color = MaterialTheme.colorScheme.onPrimary
+                    )
+                } else {
+                    Text("Login", style = MaterialTheme.typography.labelLarge)
+                }
+            }
+        }
+    }
+}
+
+// ===== PREVIEWS =====
+@Preview(showBackground = true)
+@Composable
+private fun NormalPreview() {
+    AppTheme { LoginScreenContent(LoginUiState(email = "user@example.com")) }
+}
+
+@Preview(showBackground = true)
+@Composable
+private fun LoadingPreview() {
+    AppTheme { LoginScreenContent(LoginUiState(isLoading = true)) }
+}
+
+@Preview(showBackground = true)
+@Composable
+private fun ErrorPreview() {
+    AppTheme { LoginScreenContent(LoginUiState(error = "Invalid credentials")) }
+}
+```
+
+### 2.9: Visual Parity Check ⭐
+
+Compare UI shell with original app screenshot:
+
+```markdown
+### 📸 Visual Parity: [Screen Name]
+
+Layout:
+- [ ] Structure matches original (components, sections)
+- [ ] Spacing between elements correct
+- [ ] Alignment matches
+
+Styling:
+- [ ] Colors match (background, text, buttons, header)
+- [ ] Typography matches (font size, weight)
+- [ ] Icons/images correct and positioned
+- [ ] Borders, shadows, rounded corners
+
+States:
+- [ ] Normal state displays correctly
+- [ ] Loading state — progress in right position
+- [ ] Error state — error message shows properly
+- [ ] Empty state — guidance shown
+
+Platform:
+- [ ] Material 3 conventions followed
+- [ ] Edge-to-edge / system bars handled
+- [ ] Looks good on different screen sizes
+```
+
+---
+
+## 📊 Output: Feature Blueprint + UI
+
+Use template from `templates/blueprint.md`.
+
+---
+
+## ✅ Gate (MANDATORY)
+
+```
+"📐 Blueprint + UI cho [Feature] xong:
+
+📝 Contracts:
+  - [N] domain models
+  - [N] repository interfaces
+  - [N] use case signatures
+  - [N] API endpoints
+
+🎨 UI:
+  - [Screen] implemented with mock data
+  - Resources: [N] drawables, [N] strings, [N] colors
+  - Previews: [N] states (normal, loading, error, empty)
+
+📸 Visual Parity: [OK / cần chỉnh X, Y, Z]
+
+Anh xem UI + contracts ổn không?
+→ ✅ Approve → Phase 3 (Logic Build)
+→ 🎨 Adjust UI → fix then re-check
+→ 📝 Adjust contracts → revise blueprint"
+```
+
+> ⚠️ **DO NOT proceed to Phase 3 until user approves BOTH UI and contracts.**
+
+---
+
+*Phase 2: Blueprint + UI Design — See it before you code it*