Tầm nhìn
Tài liệu này nêu sứ mệnh, tầm nhìn 3 năm, định vị và các giá trị vận hành của PhoStack — mọi quyết định sản phẩm được đối chiếu với tài liệu này.
Cập nhật lần cuối: 29/07/2026 · Một phần của bộ tài liệu PhoStack
Sứ mệnh một câu
Ship SaaS cho thị trường Việt trong 1 tuần, không phải 3 tháng — hạ tầng đặc thù Việt Nam (thanh toán, hoá đơn điện tử, Zalo) đã được viết sẵn, có mock để chạy ngay, và được theo dõi cập nhật hộ bạn. Trạng thái verify của từng module ghi công khai trong STATUS — cái nào đã chạy thật, cái nào mới có adapter.
PhoStack (phát âm: phở 🍜) là starter kit Next.js thương mại cho developer/đội ngũ xây SaaS và phần mềm bán hàng phục vụ thị trường Việt Nam.
Vấn đề
Phần lớn sản phẩm phần mềm thu tiền ở thị trường Việt đều phải tự viết lại cùng một đống hạ tầng — và dẫm phải cùng những cái bẫy:
- Ba cổng thanh toán, ba kiểu docs, ba sandbox chất lượng khác nhau. VNPay nhân amount ×100, ký HMAC trên query string sort key + encode kiểu form-urlencoded; MoMo ký theo thứ tự cố định (không phải sort) và expect HTTP 204 cho IPN; ZaloPay bắt
app_trans_idprefix ngày theo GMT+7 — bug chỉ xuất hiện lúc nửa đêm. Không cái nào nằm trong docs chính thức một cách tử tế. - Hoá đơn điện tử NĐ70/2025 (áp dụng từ 01/06/2025): phần mềm bán hàng không xuất được hoá đơn điện tử là phần mềm không bán được. Tích hợp T-VAN (Viettel SInvoice, MISA meInvoice) là rào cản lớn với đội nhỏ.
- Zalo là kênh giao tiếp mặc định của người Việt — OAuth Zalo, thông báo ZNS — nhưng các boilerplate quốc tế phổ biến không hỗ trợ.
- Boilerplate quốc tế (ShipFast, MakerKit) tốt nhưng không build cho Việt Nam: không cổng thanh toán nội địa, không hoá đơn điện tử, không VietQR, docs tiếng Anh.
Khoảng trống: một starter kit Vietnam-ready, tiếng Việt là first-class citizen, có người chịu trách nhiệm đọc docs + cập nhật khi API cổng thanh toán hoặc nghị định thuế thay đổi.
Sản phẩm
Một codebase Next.js bán license thương mại một lần (kèm 12 tháng update):
| Lớp | Nội dung |
|---|---|
| Nền | Next.js 16 + TypeScript + Prisma 7 + PostgreSQL, Zod validate mọi boundary, CI sẵn |
| Thanh toán | Interface PaymentProvider duy nhất — VNPay / MoMo / ZaloPay / Stripe / mock, đổi cổng bằng 1 dòng config; VietQR chuyển khoản |
| Pháp lý thuế | Hoá đơn điện tử NĐ70: adapter Viettel SInvoice + MISA meInvoice + mock provider |
| Zalo | Zalo OAuth, thông báo ZNS |
| SaaS core | NextAuth (Google + Zalo), multi-tenant + RBAC chống IDOR, admin panel, email transactional |
| Dữ liệu VN | Tỉnh thành sau sáp nhập |
| Docs | Tiếng Việt 🇻🇳, giải thích cả vì sao (quirk từng cổng) chứ không chỉ thế nào |
Nguyên tắc mock-first: mọi tích hợp bên thứ ba (cổng thanh toán, T-VAN, ZNS) đều có mock provider — clone repo là dev/CI chạy được ngay, không cần tài khoản sandbox hay hợp đồng nào.
Tầm nhìn 3 năm
| Chân trời | Trạng thái nhắm tới | Bằng chứng |
|---|---|---|
| Năm 1 (2026–2027) | Starter kit mặc định cho SaaS thị trường Việt | 50 license pre-order bán hết → ra mắt chính thức, cộng đồng build-in-public trên X |
| Năm 2 | Từ starter kit thành nền tảng module | Module Zalo Mini App, thêm adapter T-VAN, marketplace module cộng đồng |
| Năm 3 | "Vietnam-ready" như một tiêu chuẩn | PhoStack là câu trả lời mặc định cho câu hỏi "làm SaaS cho thị trường Việt bắt đầu từ đâu?" |
Định vị & khác biệt
"The Vietnam-ready SaaS stack. Everything in one bowl."
- Đủ bộ nội địa trong một codebase: VNPay + MoMo + ZaloPay + NĐ70 + ZNS + VietQR — chúng tôi chưa thấy starter kit nào khác gom đủ, nhưng không tuyên bố là duy nhất.
- Bán sự chịu trận, không chỉ bán code: API cổng đổi, nghị định đổi → update trong vòng 12 tháng license; khách pull code mới thay vì tự đọc lại docs.
- Tiếng Việt first-class: docs, comment, thông điệp lỗi — viết cho developer Việt.
- Giá nội địa: từ 995.000₫ (pre-order), so với $199–299+ của boilerplate quốc tế.
Giá trị vận hành
- Đọc docs hộ khách, chịu trận hộ khách — mỗi quirk tích hợp phải được ghi lại thành docs/comment tại chỗ code xử lý nó.
- Mock-first, sandbox sau — không bao giờ để CI hay dev flow phụ thuộc sandbox bên thứ ba.
- IPN là nguồn sự thật duy nhất — return URL chỉ là UI; mọi handler IPN phải idempotent.
- Fail fast — env typed bằng Zod, boot lỗi ngay thay vì undefined lúc runtime.
- Code là sản phẩm — khách trả tiền để đọc code này; mọi file phải sạch như tài liệu bán hàng.