#Cấu trúc dự án và công nghệ sử dụng

Phần lớn công việc phát triển hằng ngày cứ giao cho AI là được. Tuy nhiên khi hiểu qua cấu trúc của template, bạn sẽ đánh giá được code AI viết có đặt đúng chỗ không, và gặp vấn đề cũng dễ khoanh vùng hơn.

#Công nghệ sử dụng

Template Portal dựa trên @nocobase/portal-template-default, mã nguồn nằm tại nocobase/portal-template-default.

Bộ kết hợp này là stack frontend mà AI hiện quen thuộc nhất, nhờ đó AI viết ra có độ chính xác cao hơn.

Portal hiện là một dự án frontend thuần túy, logic nghiệp vụ được hoàn thành qua API, component chuẩn... của NocoBase. Sau này sẽ hỗ trợ để AI Agent viết cả code backend của Portal.

#Cấu trúc thư mục

src/
├── app/            Route và nạp extension
├── pages/          Đăng nhập, đăng ký, quên mật khẩu...
├── components/     Component
│   ├── ui/         Nền component shadcn/ui
│   ├── app-shell/  Bố cục, điều hướng, trạng thái loading
│   ├── auth/       Component liên quan đến xác thực
│   └── ...
├── extensions/     Extension, cài xong là dùng được
├── lib/            Phần đóng gói client NocoBase và logic ACL
├── providers/      Các provider của Refine
├── hooks/          Hook tùy chỉnh
└── locales/        Nội dung đa ngôn ngữ

Vài vị trí quan trọng:

• src/app/routes.tsx — Cấu trúc route. Route cho trạng thái đã đăng nhập và chưa đăng nhập tách riêng, route do extension cung cấp sẽ tự động được gắn vào
• src/app/extensions.tsx — Logic nạp extension, dùng import.meta.glob để quét src/extensions/*/extension.tsx
• src/providers/data.ts — data provider của Refine, dịch cú pháp truy vấn của Refine thành tham số API của NocoBase
• src/lib/nocobase/client.ts — NocoBaseClient, lớp đóng gói bên dưới của mọi request
• src/components/ui/ — Hơn 60 component shadcn/ui, dùng trực tiếp là được

Trang nghiệp vụ thường được viết dưới src/extensions/, mỗi module chức năng một thư mục. Chi tiết xem Component chuẩn và mở rộng.

#File quan trọng

#Biến môi trường

Mấy biến này nb portal dev và nb portal deploy sẽ tự động ghi sẵn, thường không cần sửa tay. Chỉ khi phía server tùy chỉnh cách lưu trữ thông tin xác thực thì mới cần chỉnh ba biến cuối cho khớp.

Khi phát triển, nếu NOCOBASE_API_URL điền địa chỉ tuyệt đối, Vite sẽ tự cấu hình một proxy để chuyển tiếp request, bạn không phải tự xử lý CORS.

#Lệnh thường dùng

Phát triển hằng ngày chỉ dùng tới chừng này lệnh; việc cài dependency, làm mới biến môi trường, build đều do CLI xử lý phía sau:

Tham số đầy đủ của từng lệnh xem Tài liệu tham khảo lệnh nb portal.

#Workspace phát triển nằm ở đâu

Workspace phát triển của Portal mặc định đặt trong thư mục nơi bạn chạy nb portal create hoặc nb portal pull:

./<portal>

Khi tạo hoặc kéo về, bạn có thể dùng --path để trỏ sang chỗ khác. Sản phẩm triển khai sau khi build nằm ở một vị trí khác, đặt dưới storage của ứng dụng đích, do nb portal deploy lo việc đồng bộ, bình thường bạn không phải quan tâm.

Không chắc workspace phát triển của Portal hiện tại nằm ở đâu thì tra thẳng:

nb portal info main

#Liên kết liên quan

• Bắt đầu nhanh với AI Portal — Chạy được entry frontend đầu tiên do AI viết
• Component chuẩn và mở rộng — Nền component shadcn/ui và cơ chế mở rộng
• Triển khai và quản lý mã nguồn — Quy trình build triển khai và source storage
• Cộng tác cùng AI Agent để xây dựng — Dùng ngôn ngữ tự nhiên điều khiển AI viết trang
• nb portal info — Xem vị trí workspace phát triển của Portal