architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture (Blueprint cố định)

架构（固定蓝图）

Đây là bộ rule KHÓA CỨNG. Agent không được tự ý đổi state management, router, hay cấu trúc thư mục giữa các lần chạy, kể cả khi thấy "cách khác hay hơn".

这是一套严格的规则。Agent不得在每次运行时自行更改状态管理、路由或目录结构，即使发现“更好的方法”也不行。

Stack đã chọn (không thương lượng lại trong project đang chạy)

已选定的技术栈（当前项目中不再协商）

State management: Riverpod (dùng codegen:
```
@riverpod
```
)
Router: GoRouter
Cấu trúc: Feature-First

Nếu project đã tồn tại và dùng stack khác, GIỮ NGUYÊN stack cũ của project, không refactor sang Riverpod/GoRouter giữa chừng trừ khi user yêu cầu rõ ràng.

状态管理： Riverpod（使用代码生成：
```
@riverpod
```
）
路由： GoRouter
结构： Feature-First

如果项目已存在并使用其他技术栈，请保留项目原有的技术栈，除非用户明确要求，否则中途不要重构为Riverpod/GoRouter。

Cấu trúc thư mục chuẩn

标准目录结构

lib/
├── app/
│   ├── router/           # GoRouter config, route names
│   └── theme/             # ThemeData, lấy từ design-system
├── core/
│   ├── constants/
│   ├── extensions/
│   └── utils/
├── shared/
│   ├── widgets/            # widget dùng chung (xem widget-library trong flutter-coding)
│   └── services/            # API client, local storage wrapper
└── feature/
    └── <ten_feature>/
        ├── data/            # models, repository implementation
        ├── domain/          # entity, repository interface (nếu cần tách)
        ├── application/     # providers (riverpod)
        └── presentation/
            ├── screens/
            └── widgets/

Mỗi feature mới (ví dụ

order

auth

profile

) PHẢI theo đúng khuôn này. Không tạo cấu trúc riêng cho từng feature.

lib/
├── app/
│   ├── router/           # GoRouter配置、路由名称
│   └── theme/             # ThemeData，取自design-system
├── core/
│   ├── constants/
│   ├── extensions/
│   └── utils/
├── shared/
│   ├── widgets/            # 通用组件（参考flutter-coding中的widget-library）
│   └── services/            # API客户端、本地存储包装器
└── feature/
    └── <ten_feature>/
        ├── data/            # 模型、仓库实现
        ├── domain/          # 实体、仓库接口（如需拆分）
        ├── application/     # providers（riverpod）
        └── presentation/
            ├── screens/
            └── widgets/

每个新功能（例如

order

、

auth

、

profile

）必须严格遵循此模板。不得为每个功能创建单独的结构。

Quy tắc package (khớp với Ponytail exclusion)

包规则（符合Ponytail exclusion）

Không tự ý thêm package mới vào
```
pubspec.yaml
```
ngoài danh sách đã duyệt:
```
flutter_riverpod
```
,
```
riverpod_annotation
```
,
```
go_router
```
,
```
dio
```
(hoặc backend SDK tương ứng),
```
freezed
```
/
```
json_serializable
```
nếu cần model codegen,
```
supabase_flutter
```
(nếu backend là Supabase - xem
```
backend-coding/SKILL.md
```
).
Nếu tính năng thực sự cần package mới không có trong danh sách → DỪNG, hỏi user xác nhận trước khi thêm, không tự thêm rồi báo sau.
```
pubspec.yaml
```
nên nằm trong vùng Ponytail exclusion - nếu agent thấy bị chặn sửa file này, đó là chủ đích, không phải lỗi.

不得在
```
pubspec.yaml
```
中添加已批准列表之外的新包：
```
flutter_riverpod
```
、
```
riverpod_annotation
```
、
```
go_router
```
、
```
dio
```
（或对应的后端SDK）、如需模型代码生成则使用
```
freezed
```
/
```
json_serializable
```
、
```
supabase_flutter
```
（如果后端是Supabase - 参考
```
backend-coding/SKILL.md
```
）。
如果功能确实需要列表中没有的新包 → 停止操作，先询问用户确认后再添加，不要自行添加后再告知。
```
pubspec.yaml
```
应处于Ponytail exclusion区域 — 如果Agent发现无法修改此文件，这是有意设置的，并非错误。

Naming convention

命名规范

File:
```
snake_case.dart
```
Class:
```
PascalCase
```

Provider:

<tenNoun>Provider

(ví dụ

cartProvider

orderListProvider

)

Route path:
```
/kebab-case
```
, route name:
```
camelCase
```

文件：
```
snake_case.dart
```
类：
```
PascalCase
```

Provider：

<tenNoun>Provider

（例如

cartProvider

、

orderListProvider

）

路由路径：
```
/kebab-case
```
，路由名称：
```
camelCase
```

Khi nào KHÔNG áp dụng skill này

何时不适用此Skill

Khi đang sửa lỗi nhỏ (typo, style) không liên quan đến vị trí file hay kiến trúc — không cần load lại skill này, xử lý trực tiếp trong
```
flutter-coding
```
.

当修复小错误（拼写错误、样式问题）且与文件位置或架构无关时 — 无需加载此Skill，直接在
```
flutter-coding
```
中处理。