Xây dựng bất cứ thứ gì. Chỉ cần mô tả.
Xây dựng một ứng dụng remote (Satellite) cho nền tảng VENI-AI là một trải nghiệm ưu tiên AI. Bạn không cần phải khởi tạo thư mục thủ công hay thiết lập các quy trình bắt tay SSO phức tạp—bạn chỉ cần mô tả yêu cầu nghiệp vụ của mình, và AI sẽ xử lý việc triển khai.
🚀 Quy trình làm việc dựa trên AI
Hướng dẫn này sử dụng Claude Code hoặc Gemini CLI để thực hiện các công việc nặng nhọc. AI hiểu toàn bộ kiến trúc monorepo, bao gồm tích hợp Shell, các pattern Ignis v2 và các tiêu chuẩn bảo mật.
1. Mở Trợ lý AI của bạn
Mở terminal tại thư mục gốc của monorepo veni-ai:
# Khởi động agent kỹ thuật tương tác
gemini# Khởi động Claude
claude2. Mô tả Ứng dụng của bạn
Sao chép mẫu câu lệnh bên dưới, điền thông tin của bạn và dán vào trợ lý AI.
Tôi muốn xây dựng một remote app mới cho VENI-AI Shell.
Tên ứng dụng: [vídụ: Inventory]
Mô tả: [vídụ: Theo dõi tồn kho kho hàng và các chuyến hàng]
Danh mục: [vídụ: Operations]
Các tính năng tôi cần:
- [Tính năng 1: vídụ: Một bảng danh sách các mặt hàng có thể tìm kiếm với mức số lượng]
- [Tính năng 2: vídụ: Một nút "Điều chỉnh kho" để mở một form modal]
- [Tính năng 3: vídụ: Tự động tô màu nổi bật cho các mặt hàng sắp hết kho]
Vui lòng:
1. Khởi tạo ứng dụng bằng CLI 'veni'.
2. Triển khai Hono API (Service, Controller, Schema).
3. Triển khai React UI (Pages, Hooks, Components).
4. Thiết lập quy trình bắt tay SSO và đăng ký với Shell.
5. Khởi chạy local để tôi có thể kiểm thử.3. Xem xét và Tinh chỉnh
AI sẽ thực hiện kế hoạch, tạo các tệp tin và chạy các lệnh cần thiết. Sau khi hoàn tất, hãy mở http://localhost:5173 để thấy ứng dụng mới của bạn hoạt động trực tiếp trong Shell.
Bạn có thể tiếp tục tinh chỉnh ứng dụng với các câu lệnh tiếp theo:
- "Thêm nút 'Xuất ra CSV' vào bảng tồn kho."
- "Chỉ những người dùng có vai trò 'Manager' mới thấy nút điều chỉnh kho."
- "Đẩy các thay đổi này lên GitHub và triển khai lên môi trường dev."
🛠️ Triển khai Thủ công (Tham chiếu SCS)
Nếu bạn muốn xây dựng thủ công hoặc cần hiểu rõ "Hợp đồng Tích hợp" bên dưới, hãy làm theo các mô hình sau.
1. Hợp đồng Tích hợp Shell
Mỗi satellite phải cung cấp một component ShellEntry thông qua Module Federation.
// apps/your-app/ui/src/federation/shell-entry.tsx
export default function ShellEntry() {
const basename = window.location.pathname.startsWith('/your-app') ? '/your-app' : '/';
return (
<BrowserRouter basename={basename}>
<App />
</BrowserRouter>
);
}2. Bắt tay Định danh (SSO)
Shell phát sóng JWT của nó thông qua BroadcastChannel. Ứng dụng của bạn phải lắng nghe và đổi nó lấy một token riêng cho service local.
| Thành phần | Trách nhiệm |
|---|---|
token-broadcast.ts | Lắng nghe Shell JWT và giải mã thông tin người dùng. |
token-exchange.ts | Gọi POST /api/auth/exchange để lấy JWT riêng của satellite. |
api-client.ts | Instance Axios tự động đính kèm scoped token vào mọi yêu cầu. |
3. Xác thực Backend (RS256)
Satellite API của bạn phải xác thực JWT của Shell bằng điểm cuối JWKS công khai: http://shell-api:3000/api/.well-known/jwks.json
📦 Các Triển khai Tham chiếu
Monorepo bao gồm các ứng dụng sẵn sàng cho production mà bạn có thể dùng làm mẫu:
| Ứng dụng | Điểm nổi bật |
|---|---|
| Drive | Thư mục phân cấp, tích hợp S3/MinIO và tìm kiếm toàn văn. |
| HRM | CRUD phức tạp, hiển thị UI dựa trên vai trò và sơ đồ tổ chức. |
| Documents | Soạn thảo văn bản phong phú, lịch sử phiên bản và quy trình phê duyệt. |
Mẹo chuyên gia
AI hiệu quả nhất khi bạn mô tả Ý định ("Tôi muốn theo dõi kho") thay vì Cách làm ("Tạo một tệp tên là ItemController.ts"). Hãy tin tưởng AI sẽ tuân thủ các tiêu chuẩn của nền tảng.