@buivietphi/skill-mobile-mt 2.0.1 → 2.2.0

package/shared/spec-to-code.md

@@ -0,0 +1,293 @@
+# Spec-to-Code — From Requirements to Implementation
+
+> On-demand module. Loaded when building new features from specs, user stories, or vague descriptions.
+> Bridges the gap between "what to build" and "how to implement it".
+
+---
+
+## Spec → Code Pipeline
+
+```
+STEP 1: PARSE SPEC (extract structured requirements)
+STEP 2: DEPENDENCY GRAPH (map what depends on what)
+STEP 3: FILE PLAN (which files to create/modify)
+STEP 4: TYPE DEFINITIONS (interfaces + branded types)
+STEP 5: IMPLEMENT (bottom-up: types → services → hooks → screens)
+STEP 6: VERIFY (against original spec checklist)
+```
+
+---
+
+## Step 1: Parse Spec → Structured Requirements
+
+Given ANY feature description, extract these 8 items:
+
+```
+┌─────────────────────────────────────────┐
+│ 1. ENTITY       What data objects?      │
+│ 2. FIELDS       What properties each?   │
+│ 3. ACTIONS      What can user do?       │
+│ 4. STATES       Loading/error/empty/ok  │
+│ 5. NAVIGATION   From where? To where?   │
+│ 6. API          Which endpoints?        │
+│ 7. STORAGE      Persist anything local? │
+│ 8. VALIDATION   Input rules?            │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Step 2: Dependency Graph Template
+
+```
+[FeatureName]Screen
+├── Components
+│   ├── [Name]Header
+│   ├── [Name]List / [Name]Card
+│   ├── [Name]Form (if editable)
+│   └── [Name]Empty / [Name]Error / [Name]Skeleton
+│
+├── Hook: use[FeatureName]
+│   ├── Query: use[Entity]Query (GET data)
+│   ├── Mutation: use[Action]Mutation (POST/PUT/DELETE)
+│   └── State: use[Store]Store (local state)
+│
+├── Service: [entity]Service.ts
+│   ├── get[Entity](params) → API call
+│   ├── create[Entity](data) → API call
+│   ├── update[Entity](id, data) → API call
+│   └── delete[Entity](id) → API call
+│
+├── Types: [entity].types.ts
+│   ├── [Entity] interface
+│   ├── Create[Entity]Input
+│   ├── Update[Entity]Input
+│   └── [Entity]Params (filters, pagination)
+│
+└── Navigation: registered in navigator
+```
+
+---
+
+## Step 3: File Plan — What Goes Where
+
+```
+RULE: Follow existing project structure. NEVER invent new patterns.
+RULE: Scan project for a SIMILAR feature. Clone its file structure.
+
+TYPICAL FILE PLAN:
+
+  src/features/[feature]/
+  ├── [Feature]Screen.tsx          ← Screen component (4 states)
+  ├── components/
+  │   ├── [Feature]Header.tsx      ← Header with title + actions
+  │   ├── [Feature]List.tsx        ← List/grid of items
+  │   ├── [Feature]Card.tsx        ← Single item card
+  │   ├── [Feature]Form.tsx        ← Form (if editable)
+  │   ├── [Feature]Skeleton.tsx    ← Loading skeleton
+  │   └── [Feature]Empty.tsx       ← Empty state
+  ├── hooks/
+  │   └── use[Feature].ts          ← Business logic hook
+  ├── services/
+  │   └── [feature]Service.ts      ← API calls
+  └── types/
+      └── [feature].types.ts       ← TypeScript interfaces
+
+  ALSO UPDATE:
+  ├── navigation/                  ← Register new screen
+  └── stores/ (if new store)       ← Only if feature needs global state
+```
+
+---
+
+## Step 4: Type-First Development
+
+```
+ALWAYS write types BEFORE implementation.
+
+ORDER:
+  1. Entity types (what data looks like)
+  2. Input types (what user submits)
+  3. API response types (what server returns)
+  4. Screen param types (navigation params)
+
+WHY: Types catch integration errors before runtime.
+     Types serve as documentation for the feature.
+     Types make code review faster (reviewer reads types first).
+```
+
+---
+
+## Step 5: Implementation Order (Bottom-Up)
+
+```
+WRONG ORDER (causes integration bugs):
+  Screen → Hook → Service → Types
+  (screen written before knowing what data looks like)
+
+RIGHT ORDER:
+  1. types/[feature].types.ts     ← Define the contract
+  2. services/[feature]Service.ts ← Implement API calls
+  3. hooks/use[Feature].ts        ← Wire service + state
+  4. components/                   ← Build UI pieces
+  5. [Feature]Screen.tsx           ← Compose everything
+  6. navigation/                   ← Register route
+
+Each step VERIFIES against the previous:
+  Service matches types? ✓
+  Hook calls service correctly? ✓
+  Component renders hook data? ✓
+  Screen composes components? ✓
+```
+
+---
+
+## Full Walkthrough Example
+
+### Spec: "Product Detail Screen"
+
+**User says:** "I need a product detail screen showing images, title, price, description, reviews, and an 'Add to Cart' button. Cart persists offline."
+
+### Parse:
+
+```
+1. ENTITY:      Product, CartItem, Review
+2. FIELDS:
+   Product  → id, title, price, description, images[], category, inStock
+   CartItem → productId, quantity, price
+   Review   → id, userId, rating, comment, createdAt
+3. ACTIONS:     View product, Add to cart, View reviews, Share
+4. STATES:      Loading (skeleton), Error (retry), Empty (404), Success
+5. NAVIGATION:  From: ProductList → To: Cart, ReviewList
+6. API:         GET /products/:id, POST /cart/items, GET /products/:id/reviews
+7. STORAGE:     Cart stored locally (MMKV) for offline
+8. VALIDATION:  Quantity ≥ 1, max 99
+```
+
+### Dependency Graph:
+
+```
+ProductDetailScreen
+├── ImageCarousel          ← Horizontal scroll, snap, indicators
+├── ProductInfo            ← Title, price, description, stock badge
+├── ReviewSummary          ← Average rating, count, "See all" link
+├── AddToCartButton        ← Quantity selector + CTA
+│
+├── useProductDetail(id)
+│   ├── useQuery(['product', id], () => productService.getById(id))
+│   └── useQuery(['reviews', id], () => productService.getReviews(id))
+│
+├── useCartStore (Zustand + MMKV persist)
+│   ├── addItem(productId, quantity, price)
+│   ├── removeItem(productId)
+│   └── items: CartItem[]
+│
+├── productService.ts
+│   ├── getById(id: ProductId): Promise<Product>
+│   └── getReviews(id: ProductId): Promise<Review[]>
+│
+└── Types
+    ├── Product, CartItem, Review
+    ├── ProductDetailParams = { productId: ProductId }
+    └── AddToCartInput = { productId: ProductId; quantity: number }
+```
+
+### File Plan:
+
+```
+src/features/product/
+├── ProductDetailScreen.tsx
+├── components/
+│   ├── ImageCarousel.tsx
+│   ├── ProductInfo.tsx
+│   ├── ReviewSummary.tsx
+│   ├── AddToCartButton.tsx
+│   └── ProductDetailSkeleton.tsx
+├── hooks/
+│   └── useProductDetail.ts
+├── services/
+│   └── productService.ts
+└── types/
+    └── product.types.ts
+
+src/stores/useCartStore.ts           ← Global (shared across features)
+navigation/types.ts                  ← Add ProductDetail params
+```
+
+### Implementation (abbreviated — types first):
+
+```typescript
+// 1. types/product.types.ts
+export interface Product {
+  id: ProductId;
+  title: string;
+  price: number;
+  description: string;
+  images: string[];
+  category: string;
+  inStock: boolean;
+}
+
+export interface Review {
+  id: string;
+  userId: UserId;
+  rating: number;  // 1-5
+  comment: string;
+  createdAt: string;
+}
+
+export interface AddToCartInput {
+  productId: ProductId;
+  quantity: number;
+}
+
+// 2. services/productService.ts
+export const productService = {
+  getById: (id: ProductId) => api.get<Product>(`/products/${id}`),
+  getReviews: (id: ProductId) => api.get<Review[]>(`/products/${id}/reviews`),
+};
+
+// 3. hooks/useProductDetail.ts
+export function useProductDetail(productId: ProductId) {
+  const product = useQuery({ queryKey: ['product', productId], queryFn: () => productService.getById(productId) });
+  const reviews = useQuery({ queryKey: ['reviews', productId], queryFn: () => productService.getReviews(productId) });
+  const addToCart = useCartStore(state => state.addItem);
+
+  return {
+    product: product.data,
+    reviews: reviews.data,
+    isLoading: product.isLoading,
+    error: product.error,
+    refetch: product.refetch,
+    handleAddToCart: (quantity: number) => {
+      if (!product.data) return;
+      addToCart(product.data.id, quantity, product.data.price);
+    },
+  };
+}
+
+// 4-5. Screen composes hook + components with 4 states
+// → Loading: <ProductDetailSkeleton />
+// → Error: <ErrorView onRetry={refetch} />
+// → Empty: <NotFoundView />
+// → Success: <ImageCarousel /> + <ProductInfo /> + <ReviewSummary /> + <AddToCartButton />
+```
+
+---
+
+## Checklist: Verify Against Spec
+
+```
+After implementing, check EVERY item from the parsed spec:
+
+□ All ENTITIES defined in types?
+□ All FIELDS present in interfaces?
+□ All ACTIONS wired to handlers?
+□ All 4 STATES rendered?
+□ NAVIGATION registered + params typed?
+□ All API endpoints called correctly?
+□ STORAGE persisted where needed?
+□ VALIDATION applied to inputs?
+□ Accessibility labels on interactive elements?
+□ Platform-specific behavior handled (iOS vs Android)?
+```

package/shared/storage-patterns.md

@@ -0,0 +1,312 @@
+# Mobile Storage Patterns
+
+> On-device storage — when to use what, how to implement correctly.
+> Covers: AsyncStorage, MMKV, SecureStore/Keychain, SQLite, WatermelonDB, Realm, SharedPreferences.
+
+---
+
+## Decision Matrix — Pick Storage Type First
+
+```
+WHAT ARE YOU STORING?          → STORAGE TO USE
+────────────────────────────────────────────────────────────────────
+Auth tokens / secrets          → SecureStore (RN) / Keychain (iOS)
+                                 EncryptedSharedPreferences (Android)
+                                 flutter_secure_storage (Flutter)
+
+App preferences / settings     → MMKV (RN, fast KV)
+(theme, language, onboarding)    SharedPreferences (Android native)
+                                 UserDefaults (iOS native)
+                                 shared_preferences (Flutter)
+
+Simple key-value cache         → MMKV (RN) / MMKV (Flutter)
+(session data, small objects)
+
+Structured relational data     → SQLite (via expo-sqlite / sqflite)
+(offline CRUD, complex queries)  WatermelonDB (RN, reactive queries)
+                                 drift (Flutter, type-safe)
+
+Large offline datasets         → WatermelonDB (RN)
+(sync with server, observables)  drift (Flutter)
+                                 Room (Android native)
+                                 CoreData / SwiftData (iOS native)
+                                 Realm (cross-platform)
+
+Files / images / documents     → FileSystem (expo-file-system / path_provider)
+                                 AsyncStorage ❌ (NOT for binary data)
+
+⛔ RULE: AsyncStorage is deprecated for RN. Use MMKV instead.
+⛔ RULE: NEVER store tokens in AsyncStorage / SharedPreferences / UserDefaults.
+```
+
+---
+
+## React Native
+
+### 1. Secure Storage (Tokens, Credentials)
+
+```typescript
+// expo-secure-store (Expo) / react-native-keychain (bare RN)
+import * as SecureStore from 'expo-secure-store';
+
+// Store
+await SecureStore.setItemAsync('accessToken', token);
+
+// Read
+const token = await SecureStore.getItemAsync('accessToken');
+
+// Delete (on logout — ALWAYS do this)
+await SecureStore.deleteItemAsync('accessToken');
+await SecureStore.deleteItemAsync('refreshToken');
+
+// RULE: On logout, delete ALL secure store keys
+async function logout() {
+  await Promise.all([
+    SecureStore.deleteItemAsync('accessToken'),
+    SecureStore.deleteItemAsync('refreshToken'),
+    SecureStore.deleteItemAsync('userId'),
+  ]);
+}
+```
+
+### 2. MMKV (Preferences + KV Cache) — 60x faster than AsyncStorage
+
+```typescript
+// react-native-mmkv
+import { MMKV } from 'react-native-mmkv';
+
+// Create instance (one per app, or per domain)
+export const storage = new MMKV();
+
+// Typed wrapper (recommended)
+export const Storage = {
+  getString: (key: string) => storage.getString(key),
+  setString: (key: string, value: string) => storage.set(key, value),
+  getBoolean: (key: string) => storage.getBoolean(key) ?? false,
+  setBoolean: (key: string, value: boolean) => storage.set(key, value),
+  getObject: <T>(key: string): T | null => {
+    const raw = storage.getString(key);
+    return raw ? JSON.parse(raw) : null;
+  },
+  setObject: <T>(key: string, value: T) => storage.set(key, JSON.stringify(value)),
+  delete: (key: string) => storage.delete(key),
+  clear: () => storage.clearAll(),
+};
+
+// With Zustand persist (recommended combo)
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+const mmkvStorage = {
+  getItem: (name: string) => storage.getString(name) ?? null,
+  setItem: (name: string, value: string) => storage.set(name, value),
+  removeItem: (name: string) => storage.delete(name),
+};
+
+export const useSettingsStore = create(
+  persist(
+    (set) => ({
+      theme: 'light',
+      language: 'en',
+      setTheme: (theme: string) => set({ theme }),
+      setLanguage: (lang: string) => set({ language: lang }),
+    }),
+    { name: 'settings', storage: createJSONStorage(() => mmkvStorage) }
+  )
+);
+```
+
+### 3. SQLite / WatermelonDB (Structured Offline Data)
+
+```typescript
+// expo-sqlite (simple queries)
+import * as SQLite from 'expo-sqlite';
+
+const db = SQLite.openDatabaseSync('app.db');
+
+// Init schema
+db.execSync(`
+  CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    completed INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL
+  )
+`);
+
+// Query
+const tasks = db.getAllSync<Task>('SELECT * FROM tasks WHERE completed = ?', [0]);
+
+// Insert
+db.runSync('INSERT INTO tasks (id, title, completed, created_at) VALUES (?, ?, ?, ?)',
+  [uuid(), 'Buy milk', 0, Date.now()]);
+```
+
+```typescript
+// WatermelonDB (reactive queries, sync-ready)
+// Best for: large datasets, reactive UI, server sync
+import { Database } from '@nozbe/watermelondb';
+import SQLiteAdapter from '@nozbe/watermelondb/adapters/sqlite';
+
+const adapter = new SQLiteAdapter({ schema, migrations });
+const database = new Database({ adapter, modelClasses: [Post, Comment] });
+
+// Observe (reactive — auto re-renders on change)
+const posts = database.get('posts').query().observe();
+```
+
+### 4. Avoid AsyncStorage (Legacy)
+
+```typescript
+// ❌ DEPRECATED — avoid in new projects
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// ✅ Migrate to MMKV:
+// Before:  await AsyncStorage.setItem('theme', 'dark');
+// After:   storage.set('theme', 'dark');
+
+// ✅ Migrate to expo-secure-store for tokens:
+// Before:  await AsyncStorage.setItem('token', jwt);
+// After:   await SecureStore.setItemAsync('token', jwt);
+```
+
+---
+
+## Flutter
+
+### 1. Secure Storage (Tokens)
+
+```dart
+// flutter_secure_storage
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+
+final _secureStorage = FlutterSecureStorage(
+  aOptions: AndroidOptions(encryptedSharedPreferences: true),
+  iOptions: IOSOptions(accessibility: KeychainAccessibility.first_unlock),
+);
+
+// Store
+await _secureStorage.write(key: 'accessToken', value: token);
+
+// Read
+final token = await _secureStorage.read(key: 'accessToken');
+
+// Delete on logout
+await _secureStorage.deleteAll();
+```
+
+### 2. SharedPreferences / Hive (KV Storage)
+
+```dart
+// shared_preferences (simple, built-in)
+final prefs = await SharedPreferences.getInstance();
+await prefs.setString('language', 'en');
+final lang = prefs.getString('language') ?? 'en';
+
+// Hive (faster, type-safe, no codegen)
+import 'package:hive_flutter/hive_flutter.dart';
+
+await Hive.initFlutter();
+final box = await Hive.openBox('settings');
+box.put('theme', 'dark');
+final theme = box.get('theme', defaultValue: 'light');
+```
+
+### 3. Drift (SQLite, type-safe)
+
+```dart
+// drift — type-safe SQLite with code generation
+@DriftDatabase(tables: [Tasks])
+class AppDatabase extends _$AppDatabase {
+  AppDatabase() : super(_openConnection());
+
+  Stream<List<Task>> watchIncompleteTasks() =>
+    (select(tasks)..where((t) => t.completed.not())).watch();
+
+  Future insertTask(TasksCompanion task) => into(tasks).insert(task);
+}
+```
+
+---
+
+## iOS Native (Swift)
+
+```swift
+// UserDefaults — preferences ONLY (not tokens)
+UserDefaults.standard.set("en", forKey: "language")
+let lang = UserDefaults.standard.string(forKey: "language") ?? "en"
+
+// Keychain — tokens and secrets
+import Security
+
+func saveToKeychain(key: String, value: String) {
+    let data = value.data(using: .utf8)!
+    let query: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrAccount as String: key,
+        kSecValueData as String: data,
+        kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+    ]
+    SecItemDelete(query as CFDictionary)
+    SecItemAdd(query as CFDictionary, nil)
+}
+
+// SwiftData / CoreData — structured offline data
+@Model class Task {
+    var id: UUID
+    var title: String
+    var completed: Bool
+    init(title: String) { self.id = UUID(); self.title = title; self.completed = false }
+}
+```
+
+---
+
+## Android Native (Kotlin)
+
+```kotlin
+// EncryptedSharedPreferences — tokens and secrets
+val masterKey = MasterKey.Builder(context)
+    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build()
+val encryptedPrefs = EncryptedSharedPreferences.create(
+    context, "secure_prefs", masterKey,
+    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+)
+encryptedPrefs.edit().putString("accessToken", token).apply()
+
+// DataStore — preferences (replaces SharedPreferences)
+val Context.dataStore by preferencesDataStore(name = "settings")
+val LANGUAGE_KEY = stringPreferencesKey("language")
+
+suspend fun saveLanguage(context: Context, lang: String) {
+    context.dataStore.edit { it[LANGUAGE_KEY] = lang }
+}
+
+val languageFlow = context.dataStore.data.map { it[LANGUAGE_KEY] ?: "en" }
+
+// Room — structured offline data
+@Entity data class Task(@PrimaryKey val id: String, val title: String, val completed: Boolean)
+@Dao interface TaskDao {
+    @Query("SELECT * FROM task WHERE completed = 0") fun getActive(): Flow<List<Task>>
+    @Insert suspend fun insert(task: Task)
+}
+```
+
+---
+
+## Security Checklist
+
+```
+✅ Tokens → SecureStore / Keychain / EncryptedSharedPreferences ONLY
+✅ On logout → delete ALL secure storage keys
+✅ Encrypt sensitive data before storing in SQLite/MMKV
+✅ Don't log stored values (console.log, print)
+✅ Use device-only accessibility (not iCloud sync for tokens)
+
+⛔ NEVER: AsyncStorage for tokens
+⛔ NEVER: UserDefaults for tokens
+⛔ NEVER: SharedPreferences (unencrypted) for tokens
+⛔ NEVER: Log token values in debug output
+⛔ NEVER: Store plain-text passwords
+```