📚 Hướng dẫn sử dụng Bộ Kỹ năng (Skills) Flutter

Tài liệu này tổng hợp toàn bộ các "Kỹ năng" (Skills) đang có sẵn trong workspace, được phân loại theo nhóm nghiệp vụ để các Agent và lập trình viên dễ dàng tra cứu, áp dụng trong dự án.

🏗️ Phase 1: Khởi tạo và Setup Dự án (Project Setup & Architecture)

Tuỳ vào quy mô của dự án, bạn hãy chọn 1 trong 2 luồng khởi tạo chính:

| Tên Skill | Chức năng chính | Khi nào sử dụng? | | :--- | :--- | :--- | | flutter-setup-enterprise-project | Orchestrator thiết lập toàn bộ dự án theo Clean Architecture, BLoC, Autogen OpenAPI. | Khi bắt đầu dự án lớn, phức tạp, yêu cầu chuẩn mực khắt khe (VD: mini_b_value). | | flutter-setup-basic-project | Orchestrator thiết lập dự án module gọn nhẹ, linh hoạt. | Khi làm app vừa/nhỏ, MVP, không cần Clean Architecture nặng nề. |

⚠️ Lưu ý cho Enterprise Project: Để sử dụng đầy đủ cấu trúc Enterprise (Autogen OpenAPI, BLoC chuẩn bvalue), bạn bắt buộc phải sử dụng skill flutter-setup-dependencies để thiết lập 3 Git Submodules vào thư mục packages/:

1. packages/core: Chứa BaseBloc, BaseState, runBlocAction (phục vụ State Management).
2. packages/network: Chứa cấu hình Networking lõi (phục vụ Autogen OpenAPI).
3. packages/base_feature: Chứa các Base Entity dùng chung (phục vụ importMappings).

Các module cấu hình riêng lẻ:

| Tên Skill | Chức năng chính | Khi nào sử dụng? | | :--- | :--- | :--- | | flutter-setup-dependencies | Thiết lập các Git Submodules (core, network, base_feature). | Bắt buộc đối với kiến trúc Enterprise. | | flutter-setup-flavor | Quản lý cấu hình nhiều môi trường (SIT, UAT, PROD). | Để tránh code nhầm API dev/prod. | | flutter-setup-injectable | Cấu hình Dependency Injection (DI) sử dụng injectable và get_it. | Khi đăng ký Service, Repository, hoặc BLoC để auto-inject. | | flutter-setup-dio | Cấu hình Networking lõi với Dio, Interceptors và DI. | Khi khởi tạo ứng dụng, chuẩn bị cho việc gọi API. | | flutter-setup-routing | Cấu hình định tuyến (Routing) an toàn kiểu bằng go_router. | Thiết lập điều hướng trang, truyền tham số, Deep Link. | | flutter-setup-state-management | Cấu hình thư viện lõi cho BLoC (BlocObserver, dependencies). | Bắt buộc để theo dõi State và Events toàn cục. | | flutter-setup-localization | Tích hợp đa ngôn ngữ (flutter_localizations, intl). | Khi ứng dụng cần hỗ trợ Tiếng Việt, Tiếng Anh... | | flutter-setup-storage | Thiết lập SharedPreferences và SecureStorage. | Lưu trữ dữ liệu cục bộ an toàn. | | flutter-setup-notification | Tích hợp Firebase Cloud Messaging (FCM). | Nhận thông báo. | | flutter-setup-linting-and-analysis | Cấu hình code analysis (linting) khắt khe. | Để đảm bảo chất lượng code team đồng nhất. | | flutter-setup-crashlytics-analytics | Tracking lỗi và hành vi người dùng (Firebase). | Khi cần giám sát độ ổn định và đo lường app. | | flutter-setup-themes | Cấu hình giao diện Sáng/Tối (Light/Dark Theme) và ThemeExtension. | Khi cần chuẩn hóa màu sắc thiết kế, Typography, hỗ trợ đổi chế độ nền. |

🚀 Phase 2: Phát triển Tính năng & Mở rộng (Feature Development & Testing)

Nhóm skill phục vụ quá trình code tính năng hàng ngày, tối ưu giao diện và kiểm thử.

🎨 1. Xây dựng Giao diện (UI & Layouts)

| Tên Skill | Chức năng chính | Khi nào sử dụng? | | :--- | :--- | :--- | | flutter-building-layouts | Hướng dẫn lắp ráp bố cục giao diện tiêu chuẩn. | Khi làm màn hình mới với Row, Column, Stack. | | flutter-build-responsive-layout | Thiết kế UI thích ứng (Responsive) bằng LayoutBuilder, Flexible. | Khi cần app hiển thị đẹp trên cả Mobile và Tablet/Web. | | flutter-building-forms | Quản lý Form, TextFormField và validate dữ liệu. | Khi làm màn hình Đăng nhập, Đăng ký, Nhập liệu. | | flutter-fix-layout-issues | Fix các lỗi kinh điển như tràn viền (RenderFlex overflowed). | Khi bị lỗi màn hình đỏ hoặc UI bị vỡ. | | flutter-animating-apps | Thêm hiệu ứng, chuyển động mượt mà vào UI. | Khi cần tăng UX bằng Micro-interactions. |

🚀 2. Quy trình Xây dựng Tính năng (Feature Implementation Pipeline)

Đây là chuỗi skill cốt lõi giúp Agent tự động hóa việc phát triển tính năng từ A-Z. Chỉ cần gọi Orchestrator, nó sẽ tự động điều phối các skill thành phần.

| Tên Skill | Chức năng chính | Khi nào sử dụng? | | :--- | :--- | :--- | | flutter-implement-feature | (Orchestrator) Triển khai toàn bộ Feature (RSD -> Data -> Domain -> BLoC -> UI). | Bắt đầu code 1 tính năng/màn hình mới từ Jira task. | | flutter-get-and-convert-to-standard-rsd | Trích xuất requirement từ Jira/Confluence/File, đối chiếu và hỏi đáp để ra bản Markdown chuẩn. | Được Orchestrator tự động gọi ở bước phân tích yêu cầu. | | flutter-auto-gen-swagger | Sinh API Service & Repository tự động từ file Swagger JSON (có tuỳ chọn cấu hình DI). | Khi Backend cung cấp Swagger (được gọi từ bước Data Layer). | | flutter-implement-data-layer | Quản lý logic gọi API và map DTO thành DMO thông qua Auto-gen (gọi skill trên) hoặc Manual. | Xử lý việc giao tiếp với Backend cho tính năng. | | flutter-implement-usecase | Khởi tạo UseCase (Domain) và inject Repository. | Đóng gói Business Logic của tính năng. | | flutter-implement-bloc-feature | Khởi tạo State Management với BLoC, Event, State, và SideEffects. | Quản lý trạng thái và thao tác UI. |

⚙️ 3. Xử lý Dữ liệu & Tối ưu hóa

| Tên Skill | Chức năng chính | Khi nào sử dụng? | | :--- | :--- | :--- | | flutter-caching-data | Chiến lược lưu trữ tạm thời (Cache) dữ liệu. | Khi cần hỗ trợ Offline hoặc tăng tốc tải trang. | | flutter-handling-concurrency | Xử lý đa luồng (Isolates) cho các tác vụ nặng. | Khi parse file JSON lớn, mã hóa phức tạp tránh đơ UI. |

🧪 4. Kiểm thử & CI/CD (Testing & Deployment)

| Tên Skill | Chức năng chính | Khi nào sử dụng? | | :--- | :--- | :--- | | flutter-add-widget-preview | Tạo preview trực quan cho Widget đang code. | Khi thiết kế Design System. | | flutter-add-widget-test | Viết test cho các thành phần UI nhỏ lẻ. | Khi cần đảm bảo một Widget luôn hoạt động đúng logic. | | flutter-add-integration-test | Giả lập luồng người dùng thực tế. | Nghiệm thu tính năng hoặc test hồi quy. | | flutter-building-plugins | Viết Plugin giao tiếp Native (Android/iOS). | Tính năng phần cứng chưa có thư viện hỗ trợ. | | flutter-ci-cd-deployment | Hướng dẫn setup Fastlane hoặc Github Actions/Gitlab CI. | Tự động hóa việc build file .apk / .ipa đẩy lên TestFlight. |