Vision

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 — mọi hạ tầng đặc thù Việt Nam (thanh toán, hoá đơn điện tử, Zalo) đã được viết sẵn, test sẵn và cập nhật hộ bạn.

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 đề

Mọi sản phẩm phần mềm bán cho 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:

1. 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_id prefix 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ế.
2. 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ỏ.
3. 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 không boilerplate quốc tế nào hỗ trợ.
4. 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 production-ready, 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."

1. Duy nhất có đủ bộ nội địa: VNPay + MoMo + ZaloPay + NĐ70 + ZNS + VietQR trong một codebase.
2. 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.
3. Tiếng Việt first-class: docs, comment, thông điệp lỗi — viết cho developer Việt.
4. 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.