
# [SYSTEM PROMPT / WORKFLOW] Kế Hoạch Chuyển Đổi Dự Án CamRecipe Pro Lên iOS & Android

> **VAI TRÒ CỦA AI:** Bạn là một Chuyên gia Phát triển Di động Cấp cao (Senior Mobile Engineer) chuyên về React Native (Expo) và Đồ họa Máy tính (GPU Image Processing). Bạn có nhiệm vụ đọc hiểu cấu trúc dưới đây và thực thi/phát triển mã nguồn theo đúng đặc tả kỹ thuật, không tự ý thay đổi stack công nghệ hoặc lược bỏ tính năng trừ khi có yêu cầu.

---

## 1. TỔNG QUAN DỰ ÁN (PROJECT OVERVIEW)
Tài liệu này phác thảo toàn bộ cấu trúc thư mục, stack công nghệ, engine xử lý hình ảnh, đặc tả thiết kế giao diện, kế hoạch debug và kiểm thử để chuyển đổi ứng dụng **CamRecipe Pro** (từ phiên bản Web nguyên mẫu hiện tại) thành một ứng dụng di động native hoàn chỉnh chạy mượt mà trên cả hai nền tảng iOS và Android.

---

## 2. STACK CÔNG NGHỆ & THƯ VIỆN SỬ DỤNG (TECHNOLOGY STACK)
Để tối ưu hóa hiệu năng (đạt mức 60 FPS) và rút ngắn thời gian phát triển, dự án sẽ áp dụng triệt để nguyên tắc tái sử dụng các thư viện chuẩn hóa (industry-standard):

| Thành phần | Công nghệ / Thư viện | Vai trò & Giải pháp tái sử dụng |
| :--- | :--- | :--- |
| **Framework chính** | `React Native` (Expo SDK mới nhất) | Nền tảng phát triển đa nền tảng (Cross-platform). |
| **Truy cập phần cứng** | `expo-camera`, `expo-location`, `expo-media-library` | Tái sử dụng API có sẵn của Expo để truy cập Camera, Định vị (GPS) và Thư viện ảnh mà không cần viết Native Bridge. |
| **Engine đồ họa** | `@shopify/react-native-skia` + `react-native-vision-camera` | Xử lý Viewfinder & Render thời gian thực. Tận dụng bộ lọc ma trận màu (`Skia.ColorFilter.Matrix`), bộ lọc tích chập (`feConvolveMatrix`) và bộ lọc nhòe (`feGaussianBlur`) trực tiếp trên GPU. |
| **Tạo kiểu giao diện** | `NativeWind` (Tailwind CSS cho React Native) | Ánh xạ 1-1 toàn bộ class Tailwind CSS từ bản Web sang Native Components. |
| **Hệ thống Icons** | `lucide-react-native` | Sử dụng trực tiếp bộ icon SVG chất lượng cao từ bản Web. |
| **Thanh trượt thông số** | `@react-native-community/slider` | Hỗ trợ vuốt chạm vật lý và Phản hồi xúc giác (Haptic Feedback) native. |
| **Bộ nhớ tạm (Local)** | `@react-native-async-storage/async-storage` | Lưu trữ cấu trúc JSON Recipes cá nhân xuống thiết bị. |
| **Trích xuất Metadata**| `exif-reader` | Giải mã dữ liệu EXIF & GPS từ ảnh trong thư viện. |

---

## 3. ĐẶC TẢ THIẾT KẾ GIAO DIỆN NGƯỜI DÙNG (UI/UX SPECIFICATION)

### A. Triết lý Thiết kế (Design System)
* **Phong cách:** Retro-Modern tối giản, cao cấp.
* **Bảng màu chủ đạo:**
    * Đen carbon: `#08080a`
    * Xám titan: `#1f1f23`
    * Vàng hổ phách: `#f59e0b`

### B. Sơ đồ bố cục màn hình (Wireframe Layout - Tỉ lệ 9:19.5)

```text
+-------------------------------------------------+
| [X] 9:41              StatusBar             [=] | -> Giả lập vùng khuyết notch/Dynamic Island
+-------------------------------------------------+
| (•) X-TRANS PRO EMULATOR     [CAMERA] [LIBRARY] | -> Header: Chế độ chụp & tải ảnh thư viện
+-------------------------------------------------+
|  +-------------------------------------------+  |
|  | [CLASSIC NEG] [DR400]        [SIM LIVE OK] |  | -> Viewfinder: Kính ngắm trực tiếp (Skia Canvas)
|  |                                           |  |    - Lớp 1: Video/Ảnh mẫu gốc
|  |                     (Grid)                |  |    - Lớp 2: Skia Shader (Màu + Khử nhiễu + Hạt)
|  |                                           |  |    - Lớp 3: PNG Frame (Trong suốt đè lên)
|  |                                           |  |    - Lớp 4: GPS Watermark (Chữ Courier Prime)
|  | [SS 1/125 f/2.8 +0.7 EV]        [ISO 3200] |  |
|  |                                           |  |
|  | 📍 PHỐ CỔ HỘI AN                          |  |
|  | 15.9000° N, 108.1500° E                   |  |
|  +-------------------------------------------+  |
+-------------------------------------------------+
|  [ Recipes ]  [ Thông số IQ ]  [ Màu & WB ]...  | -> Tab Selectors: Chuyển đổi các bảng thông số
+-------------------------------------------------+
|  [Dynamic Panels - Chiều cao cố định 250dp]     | -> Khu vực nội dung Tab đang chọn
|  - Tab Recipes: Danh sách 2 cột kèm ảnh mẫu      |
|  - Tab IQ: Thước phơi sáng, Highlight/Shadow    |
|  - Tab Màu & WB: Kelvin, Chrome Blue, Grain...  |
+-------------------------------------------------+
|  [x] Đính kèm vị trí (GPS)      [Sửa vị trí]    | -> Thanh tiện ích nhanh (Quick Utility Bar)
+-------------------------------------------------+
|   [🎨 Thư viện]       (( 🔘 ))       [📷 Preview] | -> Camera Controls: Nút Chụp & Phím tắt nhanh
+-------------------------------------------------+
|                       ===                       | -> Home Indicator ảo trên thiết bị di động
+-------------------------------------------------+

```

### C. Bản Đồ Ánh Xạ Linh Kiện (Web to React Native Mapping)

| Giao diện Web (HTML / Tailwind CSS) | Thành phần di động (React Native / NativeWind) | Vai trò & Trải nghiệm người dùng |
| --- | --- | --- |
| Main Wrapper (`max-w-md bg-black border-zinc-800 rounded-[48px]`) | `<SafeAreaView className="flex-1 bg-black">` | Khung bao bọc toàn màn hình, tự động tránh Notch tai thỏ và bo cong viền. |
| Mode Toggles (`#btn-mode-camera`, `#btn-mode-library`) | `<View className="flex-row">` + `<TouchableOpacity>` | Chuyển đổi tức thì nguồn cấp giữa Camera vật lý và Thư viện ảnh. |
| Viewfinder Wrapper (`aspect-[3/4] overflow-hidden`) | `<View style={{ aspectRatio: 3/4 }} className="relative overflow-hidden">` | Kính ngắm tỷ lệ nhiếp ảnh hoài cổ 3:4. |
| Camera Live Stream (`<video id="webcam">`) | `<Camera>` từ `react-native-vision-camera` | Kết nối camera vật lý, hỗ trợ lấy nét và đảo chiều camera. |
| GPU Sim Processing (`filter: url(#fuji-live-filter)`) | `<Canvas>` + `<Shader>` từ `@shopify/react-native-skia` | Nhận texture camera gốc, áp công thức màu GLSL/Skia Shaders (Exposure, WB, Grain) trực tiếp. |
| EXIF Geotag Watermark (`#geotag-watermark`) | `<Text style={{ fontFamily: 'Courier Prime' }} className="absolute bottom-4 left-4 text-amber-500">` | Đóng mốc địa danh và tọa độ địa lý màu hổ phách phong cách retro. |
| Tab Selectors (`#tab-recipes`, `#tab-adjust`) | `<FlatList horizontal={true}>` hoặc dãy nút bấm `<TouchableOpacity>` | Cuộn ngang mượt mà để chuyển đổi nhanh các nhóm thông số. |
| Thước kéo Ruler (`input[type="range"]`) | `@react-native-community/slider` | Thanh trượt mịn kết hợp phản hồi rung Haptic khi kéo. |
| Thư viện Recipes 2 cột (`#recipes-list-container`) | `<FlatList numColumns={2}>` | Bảng hiển thị các công thức màu. Cột trái là ảnh mẫu nạp động, cột phải là thông tin chi tiết. Chạm để kích hoạt. |
| Cửa sổ lưu (`#save-recipe-modal`) | `<Modal transparent={true} animationType="slide">` | Cửa sổ nhỏ (bottom sheet) trượt từ dưới lên cho phép nhập tên Tiếng Việt để lưu công thức. |
| Phím chụp Shutter (`button active:scale-90`) | `<TouchableOpacity className="w-16 h-16 rounded-full bg-white border-4 border-black">` | Nút chụp giả lập vật lý, có hiệu ứng nén nhẹ (scale down) khi nhấn, kích hoạt chuỗi render ảnh độ phân giải cao. |

---

## 4. KIẾN TRÚC CORE IMAGE PIPELINE ENGINE (GPU REAL-TIME)

Hệ thống xử lý hình ảnh được chia làm hai luồng hoạt động song song sử dụng React Native Skia:

### A. Luồng Kính Ngắm Live Viewfinder (Real-time GPU)

1. **Nhận Luồng Camera:** Luồng ghi trực tiếp (Camera Frame) được nạp làm texture cho Skia Canvas thông qua Native Bridge tích hợp sẵn của `react-native-vision-camera`.
2. **Bộ lọc Màu Ma Trận (Color Filter Matrix):** Tái sử dụng bộ lọc màu tích hợp của Skia nhằm tránh việc tự viết mã GLSL Shader phức tạp:
```javascript
// Áp dụng trực tiếp ma trận màu sắc có sẵn mà không cần biên dịch shader thủ công
const colorFilter = Skia.ColorFilter.Matrix(finalMatrix);

```


3. **Đồ thị Curves (Highlight/Shadow):** Thực hiện bằng bộ lọc `Skia.ColorFilter.ComponentTransfer` có sẵn, nạp các mảng giá trị `tableValues` đã tính toán trước để thay đổi cường độ điểm ảnh mà không cần can thiệp bằng CPU.
4. **Hạt Film Monochrome (Monochrome Grain):**
* Tận dụng bộ sinh nhiễu có sẵn: `Skia.Shader.MakeTurbulence(baseFrequencyX, baseFrequencyY, octaves, seed)` tạo hạt nhiễu trực tiếp trên GPU.
* Chuyển đổi màu hạt sang xám đơn sắc bằng bộ lọc `ColorFilter.Matrix` tích hợp.


5. **Clarity & Denoise (Khử Nhiễu):**
* *Denoise (Khử nhiễu):* Sử dụng bộ lọc `Skia.ImageFilter.MakeBlur(sigmaX, sigmaY, tileMode, input)` với giá trị `sigma` siêu nhỏ ($0.3 - 0.5$) để làm mịn các hạt nhiễu thô.
* *Clarity (Độ rõ nét):* Khi giá trị dương, sử dụng bộ lọc tích chập `Skia.ImageFilter.MakeMatrixConvolution` tăng độ sắc nét vùng biên. Khi giá trị âm, sử dụng bộ lọc Bloom kết hợp chế độ hòa trộn `Skia.BlendMode.Screen`.



### B. Cơ chế xuất ảnh chất lượng cao (High-Quality Export)

Khi người dùng bấm nút Shutter (Chụp):

1. Gọi API chụp ảnh tĩnh độ phân giải cao của camera vật lý.
2. Nạp ảnh tĩnh vào một `Canvas` ẩn của Skia.
3. Áp dụng chuỗi filter tương tự Viewfinder (WB, Exp, Highlight/Shadow, Grain, Denoise, Clarity).
4. Vẽ đè file PNG Frame (Khung ảnh nghệ thuật) và vẽ text chứa tọa độ GPS (Sử dụng phông chữ TrueType `Courier Prime.ttf` nạp qua `Skia.Typeface`).
5. Kết xuất ảnh sang định dạng JPEG: `image.encodeToBytes(ImageFormat.JPEG, 95)`.
6. Lưu trực tiếp vào thư viện thiết bị bằng `expo-media-library`.

---

## 5. ĐÁNH GIÁ VÀ GIẢI PHÁP CHO CÁC YÊU CẦU TỪ NGƯỜI DÙNG

| Yêu cầu từ người dùng | Giải pháp tối ưu trên Mobile bằng thư viện có sẵn |
| --- | --- |
| **Bỏ nút áp dụng, chạm thẻ kích hoạt ngay** | Sử dụng `<TouchableOpacity>` trong danh sách `FlatList` 2 cột. Kích hoạt hàm `applyRecipe()` ngay khi chạm đồng thời kích hoạt rung nhẹ (`expo-haptics`). |
| **Nhiệt độ màu WB: 2500K (Lạnh) -> 10000K (Ấm)** | Sử dụng thuật toán quy đổi Kelvin sang ma trận màu sắc (RGB), nạp trực tiếp vào component `<ColorMatrix>` tích hợp sẵn của Skia. |
| **Khử nhiễu (Denoise) giá trị âm không làm mờ tịt** | Sử dụng `Skia.ImageFilter.MakeBlur` với mức giới hạn `sigma` cực nhỏ ($0.3 - 0.5\text{px}$) kết hợp bù sáng nhẹ để triệt tiêu nhiễu hạt mịn mà không làm nhòe chi tiết ảnh. |
| **Chỉnh Đậm màu (Color) không bị lệch Tint** | Sử dụng thuộc tính bão hòa (saturation) thuần túy của bộ lọc `<ColorMatrix values={...} />` cấu hình độc lập cho từng hệ màu (Provia/Velvia) để tăng/giảm sắc độ mà không ảnh hưởng tới cân bằng trắng (Tint). |
| **Thêm thuộc tính Clarity (-10 đến +10)** | Sử dụng `Skia.ImageFilter.MakeMatrixConvolution` (tăng độ sắc nét biên khi dương) và kết hợp `MakeBlur` + `Skia.BlendMode.Screen` (tạo hiệu ứng sương mờ mượt mà khi âm). |
| **Highlight & Shadow Contrast độc lập** | Sử dụng component điều chế `<ComponentTransfer>` của Skia, nạp các dải bảng màu `tableValues` để tách biệt tương phản vùng tối và vùng sáng. |
| **Hỗ trợ tên có ký tự đặc biệt, Tiếng Việt, Emoji** | Quản lý danh sách Recipes dưới dạng mảng JSON lưu trong `AsyncStorage`. Định danh mỗi công thức bằng UUID (`uuid`) để tối ưu hóa quá trình render của `FlatList` không bị lỗi font hoặc trùng lặp định danh. |
| **Hạt đơn sắc (Monochrome Grain)** | Kết hợp bộ sinh nhiễu `<Turbulence>` của Skia cùng bộ lọc xám của `<ColorMatrix>` để sinh cấu trúc hạt xám hoài cổ trực tiếp trên GPU. |

---

## 6. KẾ HOẠCH PHÁT TRIỂN & KIỂM THỬ (MILESTONES & TESTING)

### A. Kế hoạch phát triển (4 Tuần)

* **Tuần 1: Thiết lập nền móng (Shell)**
* Khởi tạo dự án Expo SDK mới nhất. Cấu hình cấp quyền truy cập Camera, Thư viện ảnh, GPS (`Location`).
* Xây dựng giao diện Khung (UI Shell) bằng `NativeWind` và `lucide-react-native`.


* **Tuần 2: Core Image Engine (Viewfinder)**
* Tích hợp `React Native Skia` và `react-native-vision-camera`.
* Thiết lập luồng xử lý ảnh Real-time trên GPU (Color Matrix, WB, Highlight/Shadow, Denoise, Grain) hiển thị trực tiếp lên Viewfinder.


* **Tuần 3: Quản lý Recipe & Bộ nhớ tạm**
* Tích hợp `AsyncStorage` quản lý lưu/trích xuất công thức màu dưới dạng JSON.
* Xây dựng màn hình danh sách Recipes 2 cột, hiển thị Thumbnail nạp động đã áp bộ lọc tương ứng.


* **Tuần 4: Chụp ảnh độ phân giải cao & Đóng gói**
* Xây dựng mô-đun chụp ảnh tĩnh, áp bộ lọc chất lượng cao, đè PNG Frame và ghi đè Watermark GPS bằng font `Courier Prime`.
* Xuất bản thử nghiệm qua TestFlight (iOS) và Google Play Console Internal Testing (Android).



### B. Phương án Kiểm thử (Testing Plan)

* **Trên Trình giả lập (Emulators):**
* *iOS Simulator:* Kích hoạt "Simulated Camera" (vòng lặp video mẫu) để kiểm tra Skia Shader. Giả lập GPS qua `Features -> Location`.
* *Android Emulator:* Liên kết webcam máy tính làm camera đầu vào, tùy chỉnh tọa độ GPS trong Settings nâng cao của máy ảo.


* **Trên Thiết bị thật (Khuyến nghị cao nhất):**
* *Giai đoạn Alpha (Expo Go):* Quét mã QR nội bộ qua mạng WiFi để kiểm tra tốc độ phản hồi kéo thanh trượt, độ nhạy của bộ chọn công thức 2 cột, và cảm nhận phản hồi rung (`Haptics`).
* *Giai đoạn Beta (Development Builds):* Tạo build native bằng lệnh `eas build --profile development` để kiểm tra toàn diện tốc độ ghi đè tệp tin của `Media Library` và hiệu năng kết xuất ảnh gốc độ phân giải cao ($12\text{MP} - 48\text{MP}$) trực tiếp trên thiết bị thực tế.



```