Cấu Hình Dự Án (tasco.yaml)

File tasco.yaml là tệp cấu hình trung tâm nằm ở thư mục gốc của mỗi dự án SuperApp. Tệp này đóng vai trò định nghĩa các tùy chọn cấu hình sinh mã (code generators), quản lý danh sách Mini-apps và ghim phiên bản thư viện cốt lõi (BOM).

---

1. File Cấu Hình Mẫu

Dưới đây là một tệp tasco.yaml hoàn chỉnh được sinh ra tự động sau khi chạy lệnh tasco create app:

app_name: "My App"
folder_name: "my_app"
package_name: "vn.com.tasco.myapp"
architecture: "clean"
state_management: "cubit"     # cubit | bloc | riverpod | getx
di: "get_it"
network: "dio"
framework_version: "4.1.0"    # Phiên bản framework đã khởi tạo ban đầu
bom:                          # Quản lý phiên bản các thư viện lõi (BOM)
  tasco_core: "^4.1.0"
  tasco_ui_kit: "^4.1.0"
  tasco_module: "^4.1.0"
miniapps:                     # Danh sách các Mini-apps đã đăng ký hoạt động
  - orders
test:
  enabled: true
generate:                     # Bật/Tắt các thành phần sinh mã tự động
  entity: true
  repository: true
  service: true
  controller: true
  unit_test: true

---

2. Chi Tiết Các Trường Cấu Hình

Thông Tin Cơ Bản

• app_name: Tên hiển thị của ứng dụng di động.
• folder_name: Tên thư mục gốc của dự án.
• package_name: Mã định danh duy nhất của ứng dụng (Android Application ID / iOS Bundle Identifier).

Công Nghệ & Kiến Trúc

• architecture: Kiến trúc code áp dụng (mặc định là clean - Clean Architecture).
• state_management: Framework quản lý trạng thái sẽ áp dụng cho các controller được sinh ra. Hỗ trợ 4 tùy chọn:
  • cubit (Khuyến nghị): Sử dụng Cubit (tối giản từ BLoC).
  • bloc: Sử dụng Flutter BLoC (Event & State).
  • riverpod: Sử dụng các Provider của Riverpod.
  • getx: Sử dụng GetX Controller.
• di: Công cụ đăng ký & quản lý vòng đời đối tượng. Mặc định là get_it.
• network: Thư viện kết nối mạng. Mặc định sử dụng dio (được bọc trong tasco_core).

---

3. Quản Lý Phiên Bản Tập Trung (BOM)

Khối bom (Bill of Materials) định nghĩa chính xác phiên bản của các gói thư viện thuộc hệ sinh thái Tasco Mobile Framework.

important

Mỗi khi bạn chạy lệnh cập nhật hoặc thêm Mini-app mới, CLI sẽ tham chiếu đến khối bom này để kéo đúng phiên bản thư viện tương thích, tránh xảy ra xung đột phiên bản chéo (dependency hell) giữa Host Shell và các Mini-apps.

Các thư viện chính được quản lý bởi BOM bao gồm:

• tasco_core: Lõi xử lý logic, DI, Network Client.
• tasco_ui_kit: Hệ thống thành phần giao diện dùng chung và Design Tokens.
• tasco_module: Cơ chế giao tiếp, định tuyến (Routing) và vòng đời Mini-app.

---

4. Cấu Hình Bộ Sinh Mã (generate)

Khối generate cho phép nhà phát triển tùy biến những thành phần nào sẽ thực sự được sinh ra khi thực hiện lệnh gộp tasco generate resource <name>.

Tên Trường	Kiểu Dữ Liệu	Ý Nghĩa
entity	Boolean (true/false)	Sinh file Entity định nghĩa cấu trúc dữ liệu nghiệp vụ.
repository	Boolean (true/false)	Sinh Interface Repository và lớp triển khai cụ thể (Impl).
service	Boolean (true/false)	Sinh lớp Service trung gian điều phối dữ liệu từ datasource.
controller	Boolean (true/false)	Sinh Controller quản lý trạng thái giao diện (Cubit/Bloc/...).
unit_test	Boolean (true/false)	Tự động sinh file kiểm thử đơn vị tương ứng cho tầng logic.

tip

Nếu bạn đổi trường state_management từ cubit sang bloc trong tasco.yaml, các lệnh tasco generate controller sau đó sẽ tự động chuyển sang sinh cấu trúc file BLoC gồm 3 file: <name>_bloc.dart, <name>_event.dart, <name>_state.dart. Điều này giúp dự án dễ dàng chuyển dịch mô hình quản lý trạng thái khi quy mô thay đổi.