Tugrul Erdem

Hãy đóng vai một Kỹ sư Hiệu năng Di động Cấp cao (Senior Mobile Performance Engineer) và Kiến trúc sư Supabase Edge Functions.

Nhiệm vụ của bạn là thực hiện một bản phân tích chuyên sâu, đạt chuẩn thực tế (production-grade) đối với kho mã nguồn (codebase) này, tập trung nghiêm ngặt vào:

- Hành vi của ứng dụng di động Expo (React Native)
- Cách sử dụng Supabase Edge Functions
- Độ trễ khởi động lạnh (Cold start latency)
- Hiệu năng cảm nhận thực tế trên thiết bị di động (Mobile perceived performance)
- Sự kém hiệu quả về mạng + môi trường chạy (runtime) đặc thù trên các thiết bị di động

Đây KHÔNG PHẢI là nhiệm vụ tái cấu trúc mã nguồn (refactor).
Đây là nhiệm vụ PHÂN TÍCH + CHẨN ĐOÁN.
Không viết mã trừ khi được yêu cầu rõ ràng.
Không đưa ra những lời khuyên thông lệ chung chung — mọi kết luận đều phải dựa trực tiếp trên KHO MÃ NGUỒN NÀY.

---

## 1. NGỮ CẢNH & CÁC GIẢ ĐỊNH

Giả định rằng:
- Ứng dụng được xây dựng bằng Expo (chế độ managed hoặc bare)
- Nhắm tới cả hai nền tảng iOS và Android
- Supabase Edge Functions được sử dụng để xử lý logic phía backend
- Người dùng có thể đang sử dụng mạng di động chập chờn hoặc tốc độ chậm
- Độ trễ khởi động lạnh của ứng dụng (App cold start) + độ trễ khởi động lạnh của hàm Edge (Edge cold start) có thể cộng dồn chồng lên nhau

Các hàm Edge Functions chạy trên nền tảng Deno và hoạt động theo mô hình phi máy chủ (serverless).

---

## 2. MỤC TIÊU PHÂN TÍCH

Bạn phải xác định và lập tài liệu chi tiết cho các mục sau:

### A. Rủi Ro Khởi Động Lạnh Của Edge Function
- Những hàm Edge Function nào có nguy cơ cao bị ảnh hưởng bởi hiện tượng khởi động lạnh
- Lý do tại sao (kích thước gói mã bundle, các thư viện được import, hành vi lúc chạy)
- Liệu chúng có đang được gọi vào đúng những khoảnh khắc trải nghiệm người dùng (UX) nhạy cảm hay không (khi mở ứng dụng, khôi phục phiên đăng nhập, chuyển màn hình)

### B. Tác Động Lên Trải Nghiệm Người Dùng Di Động (Mobile UX)
- Những vị trí nào mà độ trễ khởi động lạnh lộ rõ trực tiếp trước mắt người dùng
- Những màn hình hoặc luồng thao tác nào đang chặn giao diện (block UI) để chờ phản hồi từ Edge
- Liệu giao diện lạc quan (optimistic UI) hoặc cơ chế thực thi chạy nền (background execution) có đang được áp dụng hay không

### C. Gánh Nặng Import & Môi Trường Chạy (Runtime Weight)
Đối với từng hàm Edge Function:
- Danh sách các thư viện được import
- Các lệnh import đang nạp ngay từ đầu (eager) hay nạp trễ khi cần (lazy)
- Các tác dụng phụ ở phạm vi toàn cục (global-scope side effects)
- Ước tính chi phí khởi động lạnh (thấp / trung bình / cao)

### D. Đặt Sai Vị Trí Kiến Trúc (Architectural Misplacements)
Chỉ ra những phần xử lý logic KHÔNG NÊN đặt bên trong Edge Functions đối với một ứng dụng di động, chẳng hạn như:
- Các lệnh gọi mô hình AI nặng
- Điều phối gọi nhiều API bên ngoài
- Các tác vụ chạy kéo dài (long-running tasks)
- Các phản hồi truyền phát luồng liên tục (streaming responses)

Giải thích rõ tại sao từng trường hợp lại gây ra vấn đề đặc biệt nghiêm trọng đối với người dùng di động.

---

## 3. PHÂN LOẠI EDGE FUNCTION

Đối với mỗi hàm Edge Function, hãy xếp nó vào MỘT trong các vai trò sau đây:

- Xác thực / Chốt chặn bảo vệ (Auth / Guard)
- Kiểm tra hợp lệ / Chính sách (Validation / Policy)
- Điều phối luồng (Orchestration)
- Tính toán nặng (Heavy compute)
- Cổng trung gian gọi API bên ngoài (External API proxy)
- Bộ kích hoạt tác vụ nền (Background job trigger)

Sau đó trả lời:
- Môi trường Edge có phải là nơi chạy đúng đắn cho vai trò này không?
- Nó nên được đặt ở Edge, Máy chủ cố định (Server) hay Tiến trình xử lý nền (Worker)?

---

## 4. PHÂN TÍCH LUỒNG ĐẶC THÙ TRÊN DI ĐỘNG

Truy vết đầu-cuối (end-to-end) các luồng hoạt động sau:

- Mở ứng dụng từ trạng thái tắt hoàn toàn (App cold start) → lệnh gọi Edge đầu tiên
- Khôi phục phiên làm việc (Session restore) → xác thực qua Edge
- Hành động do người dùng bấm kích hoạt → gửi yêu cầu tới Edge
- Chuyển ứng dụng từ chạy nền lên tiền cảnh (Background → foreground resume)

Đối với mỗi luồng:
- Xác định các lệnh gọi gây chặn giao diện (blocking calls)
- Xác định rủi ro cộng dồn hai lần khởi động lạnh (cold start stacking risks)
- Xác định các khoảng chờ đồng bộ (synchronous waits) không cần thiết

---

## 5. NGÂN SÁCH HIỆU NĂNG & ĐỘ TRỄ

Ước tính (về mặt định tính, không cần con số tuyệt đối):

- Tác động khởi động lạnh của từng Edge Function
- Hành vi khi hàm đã được làm ấm (Hot start behavior)
- Độ trễ cảm nhận thực tế trong kịch bản xấu nhất trên thiết bị di động

Sử dụng các mức phân loại:
- Vô hình / Không nhận ra (Invisible)
- Có thể nhận thấy (Noticeable)
- Phá hỏng trải nghiệm người dùng (UX-breaking)

---

## 6. ĐỊNH DẠNG BÁO CÁO PHÁT HIỆN (BẮT BUỘC)

Xuất các phát hiện của bạn theo đúng cấu trúc sau:

### 🔴 Các Vấn Đề Nghiêm Trọng (Critical Issues)
Những vấn đề trực tiếp làm tổn hại đến trải nghiệm người dùng trên di động.

### 🟠 Các Rủi Ro Trung Bình (Moderate Risks)
Những vấn đề khó mở rộng quy mô hoặc làm giảm tỷ lệ giữ chân người dùng.

### 🟢 Các Khu Vực Chấp Nhận Được / Được Thiết Kế Tốt
Những quyết định kiến trúc đúng đắn đáng để duy trì.

---

## 7. KHUYẾN NGHỊ (QUY TẮC NGHIÊM NGẶT)

- Các khuyến nghị phải gắn cụ thể với kho mã nguồn này
- Mỗi khuyến nghị phải bao gồm:
  - Cần thay đổi cái gì
  - Tại sao (lập luận dưới góc độ thiết bị di động + môi trường Edge)
  - Tác động kỳ vọng (trải nghiệm UX, độ trễ, độ tin cậy)

TUYỆT ĐỐI KHÔNG:
- Viết lại mã nguồn
- Đưa thêm các framework mới vào
- Tối ưu hóa quá mức khi chưa cần thiết

---

## 8. PHÁN QUYẾT CUỐI CÙNG (FINAL VERDICT)

Trả lời một cách tường minh, dứt khoát:
- Kiến trúc hiện tại có phù hợp với ứng dụng di động không?
- Edge Functions đang bị lạm dụng quá mức, sử dụng dưới mức cần thiết hay đã dùng đúng chỗ?
- Đâu là một cải tiến duy nhất mang lại tác động lớn nhất?

---

## CÁC QUY TẮC QUAN TRỌNG

- Hãy giữ thái độ phê bình sắc bén và có chính kiến rõ ràng
- Giả định rằng ứng dụng này hướng tới chất lượng trải nghiệm UX chuẩn thương mại (production-quality)
- Coi độ trễ khởi động lạnh là một vấn đề HẠNG NHẤT cần ưu tiên giải quyết
- Luôn ưu tiên cảm nhận thực tế trên thiết bị di động hơn là sự hào nhoáng của kiến trúc backend

Hãy đóng vai một Kiến trúc sư Expo + Supabase Cấp cao (Senior Expo + Supabase Architect).

Triển khai một kiến trúc "an toàn trước hiện tượng khởi động lạnh" (“cold-start safe” architecture) sử dụng:
- Ứng dụng khách (client) viết bằng Expo (React Native)
- Supabase Postgres + Storage + Realtime
- Supabase Edge Functions CHỈ dùng cho việc kiểm tra cổng truy cập nhẹ (lightweight gating) + đẩy tác vụ vào hàng đợi (job enqueue)
- Một dịch vụ Worker tách biệt chuyên xử lý các tác vụ tạo sinh AI (AI generation) nặng và ghi dữ liệu vào kho lưu trữ (storage writes)

Bàn giao:
1) Lược đồ cơ sở dữ liệu (các bản SQL migrations) cho các bảng: `jobs`, `generations`, `entitlements` (`credits`/`is_paid`), bao gồm đầy đủ chỉ mục (indexes) và ghi chú về bảo mật cấp độ dòng (RLS)
2) Các hàm Edge Functions:
   - `ping` (HEAD/GET)
   - `enqueue_generation` (xác thực người dùng, kiểm tra `is_paid`/`credits`, tạo bản ghi job, trả về `jobId`)
   - `get_job_status` (truy vấn đọc nhẹ)
   Giữ các lệnh import ở mức tối thiểu; tuyệt đối không nạp các bộ SDK nặng.
3) Luồng hoạt động trên ứng dụng khách Expo:
   - gọi lệnh `ping` làm ấm (warm ping) không chặn luồng chính (non-blocking) ngay khi khởi động ứng dụng
   - Nút Generate sử dụng giao diện phản hồi lạc quan (optimistic UI) + khung giữ chỗ (placeholder)
   - đăng ký lắng nghe cập nhật trạng thái job qua Realtime hoặc triển khai cơ chế hỏi vòng (polling) dự phòng
   - kết quả tạo sinh cuối cùng sẽ thay thế khung giữ chỗ trong danh sách thư viện ảnh (gallery list)
4) Trách nhiệm của Worker (mô tả giao diện giao tiếp và các điểm cuối/logic tối thiểu, không xây dựng dư thừa quá mức):
   - lấy các job đang chờ trong hàng đợi (`queued`)
   - chạy tác vụ tạo sinh AI
   - tải kết quả lên kho lưu trữ (storage)
   - cập nhật bảng `jobs` + chèn bản ghi vào bảng `generations`
   - chính sách thử lại (retry policy) và đảm bảo tính lũy đẳng (idempotency)

Các ràng buộc:
- KHÔNG ĐƯỢC chặn quá trình mở ứng dụng vì bất kỳ lệnh gọi Edge nào
- KHÔNG ĐƯỢC chạy các lệnh gọi AI bên trong Edge Functions
- Đảm bảo các job bị lỗi vẫn tạo ra một bản ghi trong bảng `generations` có hiển thị rõ thông tin đầu vào ban đầu
- Giữ cho giải pháp đạt chuẩn sẵn sàng cho môi trường production nhưng tinh gọn tối đa

Đầu ra phải được cấu trúc theo đúng các phần:
A) Tóm tắt kiến trúc
B) Các bản di chuyển dữ liệu (SQL Migrations)
C) Cấu trúc tệp Edge Function + các khối mã chính
D) Ghi chú tích hợp trên Expo + các khối mã chính
E) Phác thảo Worker + mã giả (pseudo-code)

Tích hợp PostHog Cấp độ Production cho Next.js 15 (App Router)
Vai trò
Bạn là một Kiến trúc sư Next.js Cấp cao & Kỹ sư Phân tích Dữ liệu (Analytics Engineer) với chuyên môn sâu về Next.js 15, React 19, Supabase Auth, thanh toán Polar.sh và PostHog.
Bạn thiết kế các hệ thống đạt chuẩn vận hành thực tế (production-grade), tôn trọng quyền riêng tư và xử lý chính xác ranh giới nghiêm ngặt giữa Server và Client của Next.js 15.
Kết quả đầu ra của bạn phải lấy mã nguồn làm trọng tâm (code-first), mang tính tất định (deterministic) và phù hợp cho một sản phẩm SaaS thực tế vào năm 2026.

Mục tiêu
Tích hợp PostHog Analytics, Ghi lại Phiên người dùng (Session Replay), Cờ Tính năng (Feature Flags) và Theo dõi Lỗi (Error Tracking) vào một ứng dụng SaaS dùng Next.js 15 App Router với:
- Sự phân tách chuẩn xác giữa Server / Client (theo mẫu thiết kế Providers Pattern)
- Lớp phân tích dữ liệu tập trung, an toàn kiểu dữ liệu (type-safe)
- Vòng đời định danh người dùng được đồng bộ hóa với Supabase
- Theo dõi thanh toán và doanh thu chính xác (Polar)
- Theo dõi điều hướng trang SPA an toàn với cơ chế `<Suspense>`

Bối cảnh Kỹ thuật
- Framework: Next.js 15 (App Router) & React 19
- Cơ chế kết xuất (Rendering): Server Components (mặc định), Client Components (cho tương tác)
- Xác thực (Auth): Supabase Auth
- Thanh toán (Billing): Polar.sh
- Trạng thái hiện tại: Chưa có công cụ phân tích nào
- Môi trường: Web SaaS (môi trường production)

Các Quy tắc Kiến trúc Cốt lõi (BẤT DI BẤT DỊCH)
1. PostHog CHỈ ĐƯỢC PHÉP chạy trong các Client Components.
2. Tuyệt đối không gọi PostHog trong Server Components, Route Handlers hoặc các API routes.
3. Định danh người dùng chỉ được kiểm soát duy nhất bởi trạng thái xác thực (auth state).
4. Toàn bộ các lệnh gọi phân tích dữ liệu bắt buộc phải đi qua một lớp trừu tượng duy nhất (`lib/analytics.ts`).

1. Kiến trúc & Thiết lập (Mẫu thiết kế Providers Pattern)
- Tạo tệp `app/providers.tsx`.
- Đánh dấu tệp này bằng chỉ thị `'use client'`.
- Khởi tạo PostHog bên trong component này.
- Bọc toàn bộ ứng dụng bằng `PostHogProvider`.
- Cấu hình:
  - Sử dụng biến môi trường `NEXT_PUBLIC_POSTHOG_KEY` và `NEXT_PUBLIC_POSTHOG_HOST`.
  - `capture_pageview`: `false` (Được xử lý thủ công để tránh việc ghi nhận trùng lặp trong App Router).
  - `capture_pageleave`: `true`.
  - Bật tính năng Session Replay (`mask_all_text_inputs: true`).

2. Vòng đời Định danh Người dùng (Đồng bộ với Supabase)
- Tạo tệp `hooks/useAnalyticsAuth.ts`.
- Lắng nghe sự kiện `onAuthStateChange` của Supabase.
- Logic xử lý:
  - `SIGNED_IN`: Gọi hàm `posthog.identify`.
  - `SIGNED_OUT`: Gọi hàm `posthog.reset()`.
  - Sử dụng các hook phù hợp của React 19 nếu cần cho việc quản lý trạng thái, nhưng dùng `useEffect` tiêu chuẩn vẫn hoàn toàn ổn đối với các bộ lắng nghe sự kiện (listeners).

3. Thanh toán & Doanh thu (Polar)
- Thuộc tính `distinct_id` của PostHog bắt buộc phải khớp với Supabase User ID.
- Thiết lập `polar_customer_id` làm một thuộc tính người dùng (user property).
- Theo dõi các sự kiện: `CHECKOUT_STARTED`, `SUBSCRIPTION_CREATED`.
- Đảm bảo sự kiện `SUBSCRIPTION_CREATED` bao gồm `{ revenue: number, currency: string }` để phục vụ cho bảng điều khiển Doanh thu (Revenue dashboards) của PostHog.

4. Lớp Phân tích Dữ liệu An toàn Kiểu (Type-Safe Analytics Layer)
- Tạo tệp `lib/analytics.ts`.
- Định nghĩa kiểu liệt kê nghiêm ngặt `AnalyticsEvents` (Enum).
- Xuất (export) hàm bọc `trackEvent` có kiểm tra kiểu chặt chẽ.
- Kiểm tra điều kiện `if (typeof window === 'undefined')` để ngăn chặn lỗi khi kết xuất phía máy chủ (SSR).

5. Theo dõi Điều hướng SPA (An toàn cho Next.js 15 & Suspense)
- Tạo tệp `components/PostHogPageView.tsx`.
- Sử dụng `usePathname` và `useSearchParams`.
- QUAN TRỌNG: Vì hook `useSearchParams` sẽ khiến toàn bộ trang bị lùi về kết xuất phía client (client-side rendering de-opt) trong Next.js 15 nếu không được bọc kỹ, bạn BẮT BUỘC phải bọc component này bên trong một ranh giới `<Suspense>` khi gắn (mount) nó vào trong `app/providers.tsx`.
- Kích hoạt ghi nhận lượt xem trang (pageviews) mỗi khi đường dẫn (route) thay đổi.

6. Theo dõi Lỗi (Error Tracking)
- Bắt và ghi nhận lỗi một cách tường minh: `posthog.capture('$exception', { message, stack })`.

Sản phẩm Bàn giao (BẮT BUỘC)
CHỈ trả về đúng các tệp sau đây:
1. `package.json` (Thư viện phụ thuộc: `posthog-js`).
2. `app/providers.tsx` (Có kèm khung bọc Suspense).
3. `lib/analytics.ts` (Lớp trừu tượng an toàn kiểu dữ liệu).
4. `hooks/useAnalyticsAuth.ts` (Đồng bộ xác thực).
5. `components/PostHogPageView.tsx` (Theo dõi điều hướng trang).
6. `app/layout.tsx` (Ví dụ tích hợp vào bố cục gốc Root layout).

🚫 Không thêm bất kỳ tệp dư thừa nào khác.
🚫 Không viết văn xuôi giải thích bên ngoài các dòng chú thích mã nguồn (code comments).