Đặc tả ứng dụng cho Builder – theo mô hình Ever Gauzy
Cập nhật: 2026-10-17
Các nghiệp vụ của Ever Gauzy được tách thành 13 app, mỗi app một file độc lập để giao việc. 6 app xây mới bằng builder (prompt chia lượt, có checklist); 6 app bổ sung vào hrm và 1 app bổ sung vào calendar.
Danh sách file
| File | App | Hướng | Đợt |
|---|---|---|---|
| app-01-nhan-su.md | 1. Nhân sự | Bổ sung vào hrm | Song song (backlog hrm) |
| app-02-nghi-phep.md | 2. Nghỉ phép & ngày lễ | Bổ sung vào hrm | Song song (backlog hrm) |
| app-03-thiet-bi.md | 3. Thiết bị & mượn thiết bị | Bổ sung vào hrm | Song song (backlog hrm) |
| app-04-ghi-gio-timesheet.md | 4. Ghi giờ theo dự án & Timesheet | Xây mới bằng builder | Đợt 2 |
| app-05-tuyen-dung.md | 5. Tuyển dụng (ATS) | Bổ sung vào hrm | Song song (backlog hrm) |
| app-06-du-an-cong-viec.md | 6. Dự án, công việc & sprint | Xây mới bằng builder | Đợt 2 |
| app-07-crm.md | 7. CRM: liên hệ, pipeline, deal, đề xuất | Xây mới bằng builder | Đợt 1 |
| app-08-hoa-don-thanh-toan.md | 8. Hóa đơn, báo giá & thanh toán | Xây mới bằng builder | Đợt 2 (cuối) |
| app-09-chi-phi-thu-nhap.md | 9. Chi phí, nhà cung cấp & thu nhập | Xây mới bằng builder | Đợt 2 |
| app-10-luong.md | 10. Lương | Bổ sung vào hrm | Song song (backlog hrm) |
| app-11-san-pham-kho.md | 11. Sản phẩm & kho | Xây mới bằng builder | Đợt 1 |
| app-12-okr-kpi.md | 12. Mục tiêu OKR/KPI | Bổ sung vào hrm | Song song (backlog hrm) |
| app-13-lich-hen-cuoc-hop.md | 13. Lịch hẹn & cuộc họp | Bổ sung vào calendar (dùng builder) | Song song |
Khuôn đặc tả của mỗi app
- Mục đích: vấn đề app giải quyết và ai dùng.
- Vai trò & quyền: ai được xem, tạo, sửa, duyệt gì.
- Dữ liệu: các thực thể và trường, kiểu dữ liệu, bắt buộc hay không.
- Trạng thái: vòng đời và ai được chuyển trạng thái.
- Quy tắc nghiệp vụ: điều phải kiểm tra ở server (builder đánh giá điểm này).
- Màn hình: danh sách màn hình và thao tác chính.
- Prompt cho builder – chia lượt (app xây mới) hoặc Prompt tham khảo (app bổ sung vào hrm), kèm checklist kiểm tra trước khi Publish.
Vì sao cần đặc tả chi tiết – kết quả thử nghiệm
Ngày 17/10/2026, App 11 (Sản phẩm & kho) được dựng trên builder dev theo hai cách, mỗi cách chạy 2 lần (Sonnet 5.5, chia pha):
- Prompt ngắn: 3 dòng, kiểu người dùng hay viết ("sản phẩm có biến thể, nhiều kho, phiếu nhập/xuất/chuyển, có quản trị, thủ kho và nhân viên bán hàng").
- Đặc tả: nguyên văn lượt 1 trong app-11-san-pham-kho.md.
Cả hai cách được chấm trên cùng 14 tiêu chí lấy từ quy tắc và checklist của App 11. Trong đó 11 tiêu chí do judge của builder chấm, và judge phải trích được dòng code thì tiêu chí mới tính là đạt.
| Cách viết | Tiêu chí đạt | Thời gian | Chi phí |
|---|---|---|---|
| Prompt ngắn – lần 1 | 9/14 | 17 phút | $6,19 |
| Prompt ngắn – lần 2 | 9/14 | 26 phút | $7,28 |
| Đặc tả – lần 1 | 14/14 | 27 phút | $9,52 |
| Đặc tả – lần 2 | 14/14 | 42 phút | $14,69 |
Prompt ngắn trượt đúng 5 tiêu chí giống nhau ở cả hai lần:
- thủ kho thao tác được mọi kho, không chỉ kho mình phụ trách;
- API trả cả giá vốn cho nhân viên bán hàng;
- không có loại sản phẩm Dịch vụ;
- xóa sản phẩm hoặc kho còn tồn mà không bị chặn;
- cờ "sắp hết" dùng ngưỡng cố định là 10 thay vì mức tối thiểu riêng cho từng mặt hàng.
App vẫn build được và mọi kiểm tra tự động đều xanh, nên người không đọc code sẽ không thấy các lỗi này. Hai lần chạy prompt ngắn còn ra hai phạm vi khác nhau (một lần có thẻ kho, một lần không). Hai lần chạy đặc tả cho ra cùng một kế hoạch.
Rút ra:
- Builder không tự nghĩ ra quy tắc mà prompt không nêu, và cũng không hỏi lại.
- Đặc tả tốn hơn khoảng $5 mỗi app, chủ yếu vì app làm thêm phần nhân viên lấy từ hrm và tách dữ liệu theo tổ chức. Khoản này rẻ hơn nhiều so với việc phát hiện lỗi phân quyền sau khi đã Publish.
- Kết quả mới có từ 1 app với 2 lần chạy mỗi cách. Judge chỉ đọc code, chưa chạy app, nên vẫn phải kiểm tra bằng từng vai trò theo checklist.
Hai prompt và bộ tiêu chí nằm trong bộ eval của builder (eval/prompts/21-kho-ngan.md, 22-kho-dac-ta.md, VENIZIA-AI/veni-builder#1361), dùng để đo lại khi builder thay đổi.
Danh sách app
| # | App | Hướng | Lý do / phụ thuộc |
|---|---|---|---|
| 1 | Nhân sự | Bổ sung vào hrm | hrm đã có hồ sơ, phòng ban dạng cây, quản lý trực tiếp, kỹ năng, khen thưởng, onboarding/offboarding |
| 2 | Nghỉ phép & ngày lễ | Bổ sung vào hrm | Đã có chính sách nghỉ, số dư, đơn nghỉ, ngày lễ |
| 3 | Thiết bị | Bổ sung vào hrm | Đã có cấp phát tài sản cho nhân viên; thiếu kho thiết bị và mượn có duyệt |
| 4 | Ghi giờ theo dự án & Timesheet | Xây mới | hrm có chấm công theo ca (check-in/out, OT), khác nghiệp vụ ghi giờ theo dự án; phụ thuộc 6 |
| 5 | Tuyển dụng | Bổ sung vào hrm | Đã có tin tuyển, hồ sơ ứng tuyển, phỏng vấn, phiếu đánh giá, offer |
| 6 | Dự án, công việc & sprint | Xây mới | Phụ thuộc 7 (khách hàng) |
| 7 | CRM | Xây mới | Độc lập |
| 8 | Hóa đơn & thanh toán | Xây mới | Phụ thuộc 7, 11, 4, 9 |
| 9 | Chi phí & thu nhập | Xây mới | Phụ thuộc 7 |
| 10 | Lương | Bổ sung vào hrm | Bảng lương (pay run) đang nằm trong hrm; repo payroll chỉ là khung trống |
| 11 | Sản phẩm & kho | Xây mới | Độc lập |
| 12 | Mục tiêu OKR/KPI | Bổ sung vào hrm | Mở rộng module đánh giá hiệu suất (đã có mục tiêu cá nhân theo chu kỳ) |
| 13 | Lịch hẹn & cuộc họp | Bổ sung vào calendar | Repo calendar mới là khung giao diện |
6 app xây mới bằng builder; 7 app còn lại dùng đặc tả làm danh sách tính năng bổ sung cho hrm và calendar. Mỗi app bổ sung có dòng Hướng ghi rõ phần đã có và phần còn thiếu.
Thứ tự xây đề xuất
- Đợt 0 (trong hrm, điều kiện cho các app mới): bổ sung sự kiện nhân viên và phòng ban (xem mục Nguồn dữ liệu nhân viên).
- Đợt 1 (xây mới, không cần phòng ban): 7 CRM, 11 Sản phẩm & kho. Làm song song với đợt 0.
- Đợt 2 (xây mới, cần nhân viên/phòng ban từ hrm): 6 Dự án, 9 Chi phí, rồi 4 Ghi giờ và 8 Hóa đơn.
- Song song: backlog bổ sung cho hrm (1, 2, 3, 5, 10, 12) và calendar (13), làm như tính năng của app đó.
Giả định chung cho mọi app
- Người dùng: mỗi app nhận diện người dùng qua đăng nhập Shell. Vai trò dùng chung: Quản trị, Quản lý (theo phòng ban/team), Nhân viên.
- Nhân viên, phòng ban, quản lý: lấy từ hrm theo mô hình ở mục Nguồn dữ liệu nhân viên bên dưới; app mới không tự quản lý danh sách này.
- Tiền tệ và ngày: VND là mặc định, tuần bắt đầu thứ Hai, giao diện tiếng Việt.
- Xóa: dữ liệu nghiệp vụ chỉ xóa mềm (đánh dấu không hoạt động), không xóa hẳn.
Nguồn dữ liệu nhân viên
Khuyến nghị: hrm là nơi duy nhất tạo và sửa nhân viên, phòng ban, quan hệ quản lý. Mỗi app mới giữ một bản sao chỉ đọc của các dữ liệu này, cập nhật qua sự kiện Redis Streams mà hrm phát ra. Đây đúng là quy ước của nền tảng: app không đọc database của app khác, mặc định dùng bản sao cục bộ nuôi bằng sự kiện (veni-docs/develop/build/cross-system.md), và builder đã có capability integration cho việc này.
App mới không ghi ngược vào hrm; muốn sửa nhân viên hoặc phòng ban thì sửa trong hrm.
| Phương án | Đánh giá |
|---|---|
| Bản sao cục bộ nuôi bằng sự kiện từ hrm (khuyến nghị) | Một nguồn sự thật; app vẫn chạy khi hrm tạm lỗi; lọc theo phòng ban chạy ngay trong database của app. Cần hrm bổ sung sự kiện (bên dưới) |
| Gọi API hrm mỗi lần cần (chuyển tiếp token người dùng, như app assistant đang làm) | Chỉ chạy nếu người dùng có quyền đọc trong hrm; không chạy được tác vụ nền vì nền tảng chưa có credential giữa các dịch vụ; hrm chậm hoặc lỗi thì app cũng lỗi |
| Mỗi app tự quản lý nhân viên | Nhập liệu nhiều lần, dữ liệu lệch nhau giữa các app; không nên dùng |
Việc cần làm trong hrm trước (đợt 0). Hiện hrm phát hrm:stream:employees nhưng sự kiện chỉ có mã nhân viên, mã user, mã tổ chức và chức danh; chưa có sự kiện phòng ban.
- Thêm vào sự kiện
employee.*: họ tên, email, mã user Shell, phòng ban, quản lý trực tiếp, trạng thái. - Thêm sự kiện phòng ban: tạo, đổi tên, chuyển phòng ban cha, xóa.
- Cách nạp dữ liệu ban đầu cho app mới: quản trị bấm phát lại toàn bộ nhân viên và phòng ban vào stream (backfill một lần).
Trong app mới: bật integration, tạo hai bảng chỉ đọc "nhân viên" (mã, mã user Shell, họ tên, email, phòng ban, quản lý, trạng thái) và "phòng ban" (mã, tên, phòng ban cha). Người đăng nhập được khớp với nhân viên qua mã user Shell. Thêm vào prompt của app mới câu: "Nhân viên và phòng ban không tự quản lý mà lấy từ sự kiện của app hrm (hrm:stream:employees, sự kiện phòng ban) vào bảng chỉ đọc."
Trước khi đợt 0 xong: xây các app không cần phòng ban (CRM, Kho). Nếu cần danh sách người dùng sớm, đọc shell:stream:users của Shell; nguồn này chỉ có người dùng và tư cách thành viên tổ chức, không có phòng ban.
Liên kết dữ liệu giữa các app mới
Các app không chờ nhau: mỗi app dùng bảng tham chiếu có dữ liệu mẫu cho dữ liệu của app khác, rồi ở lượt cuối thay bằng dữ liệu đồng bộ qua sự kiện Redis Streams. App phát sự kiện có lượt "Phát sự kiện cho app khác"; app nhận có lượt "Nối … thật".
| App phát | Dữ liệu | App nhận |
|---|---|---|
| hrm | nhân viên, phòng ban, đơn nghỉ đã duyệt | 4, 6, 7, 8, 9, 11, 13 |
| 7 CRM | liên hệ (khách hàng) | 6, 8, 9 |
| 6 Dự án | dự án, task | 4, 9 |
| 11 Kho | sản phẩm, biến thể, giá bán (không có giá vốn) | 8 |
| 4 Ghi giờ | giờ làm, trạng thái duyệt, tính phí | 8 |
| 9 Chi phí | chi phí tính lại cho khách đã duyệt | 8 |
Thứ tự nối: xây lượt phát sự kiện của app phát trước, rồi mới chạy lượt "Nối … thật" của app nhận. Phần này chỉ kiểm tra được trên dev sau khi Publish (bản xem trước không có Redis).
Cách chạy trên builder
- Dùng builder môi trường dev. Builder prod xuất bản thẳng lên prod, không qua dev.
- Mỗi app một phiên, chạy theo từng lượt trong file của app. Lượt 1 chỉ có phần lõi (tối đa khoảng 5 bảng): builder tự chia việc khi kế hoạch có hơn 5 bảng hoặc hơn 6 màn hình, và mỗi lượt giới hạn 45 phút.
- Duyệt kế hoạch kỹ nhưng nhanh. Kiểm tra bảng, màn hình và danh sách capability (cần
database,authz; app đọc nhân viên từ hrm cầnintegration). Thiếu thì bấm yêu cầu sửa kế hoạch. Kế hoạch chờ duyệt vẫn chiếm phiên. - Kiểm tra trong bản xem trước bằng từng vai trò rồi mới sang lượt sau. Đọc tab Changes trước khi duyệt thay đổi cấu trúc dữ liệu: undo và rollback không hoàn tác dữ liệu hay migration.
- Màn báo cáo, dashboard để lượt cuối: màn viết tay tốn gấp khoảng 2 lần màn CRUD sinh tự động.
- Publish khi qua checklist của app và checklist chung bên dưới.
Mọi prompt đã có sẵn hai câu bắt buộc: "Mọi dữ liệu tách theo tổ chức của người đăng nhập" (builder chưa tự sinh việc tách dữ liệu theo tổ chức) và câu dữ liệu mẫu cho bảng nhân viên (bản xem trước không có Redis nên phần đọc sự kiện hrm không chạy; kiểm tra phần này trên dev sau khi Publish).
Giới hạn cần biết
| Giới hạn | Giá trị |
|---|---|
| Độ dài một prompt | 20.000 ký tự |
| Một lượt build | 45 phút, 300 bước |
| Lập kế hoạch | 5 phút |
| Phiên đồng thời mỗi tổ chức (prod) | 2 |
| Chi phí mỗi tổ chức mỗi ngày (prod) | $50 |
| Phiên không thao tác (prod) | tự đóng sau 12 phút |
| Thời gian thường gặp | app mới khoảng 4 phút, lượt bổ sung khoảng 1,5 phút |
Chạy lần lượt từng app, tối đa 2 app song song.
Checklist chung trước khi Publish
- [ ] Quy tắc được chặn ở API, không chỉ ẩn trên giao diện (thử gọi thẳng API hoặc thao tác bằng vai trò không có quyền).
- [ ] Phân quyền đúng phạm vi: quản lý chỉ thấy phòng mình, nhân viên chỉ thấy dữ liệu của mình.
- [ ] Dữ liệu tổ chức A không thấy được từ tổ chức B.
- [ ] Các số tổng và số tiền tính ở API.
- [ ] Báo cáo hiện số thật, không phải toàn số 0 (lỗi API và màn hình lệch dữ liệu từng lọt qua mọi kiểm tra tự động).
- [ ] Sau khi Publish lên dev: bảng nhân viên/phòng ban được nạp từ sự kiện hrm.
Ngoài phạm vi builder
Builder sinh app web (API + giao diện) chạy trong Shell, nên các thành phần dưới đây không xây được bằng một prompt.
| Thành phần Gauzy | Vì sao ngoài phạm vi | Hướng thay thế |
|---|---|---|
| Desktop Timer (chụp màn hình, đo bàn phím/chuột, phát hiện idle) | Cần app cài trên máy (Electron) và quyền hệ điều hành | App 4 dùng đồng hồ trên web và nhập tay; nếu cần giám sát thì làm dự án desktop riêng gọi API của App 4 |
| Browser Extension | Tiện ích trình duyệt, không phải app web | Không làm ở bản đầu |
| Desktop Server | Đóng gói cả backend để tự host | Không cần: các app chạy trên cụm VENI |
| Mobile app | App gốc cho điện thoại | Giao diện web responsive của từng app |
| AI Agent Chat | Tính năng cấp nền tảng, không thuộc một app | Dùng app assistant của VENI |
| Documents Hub | VENI đã có app cùng phạm vi | Dùng app document và drive |
| Đa tổ chức, phân quyền chung, email template, SMTP, branding | Thuộc Shell và nền tảng | Shell quản lý tổ chức và đăng nhập; mỗi app chỉ khai báo vai trò của mình |
| Đồng bộ GitHub/Jira, Stripe/PayPal, Google Calendar | Tích hợp bên ngoài cần khóa API và webhook | Làm sau bản đầu, từng tích hợp một |