EN
SaaS
Đang vận hành

S Store — nền tảng quản lý cửa hàng bán lẻ (Web · iOS · Android)

S Store gom bán hàng, kho, ca làm, chấm công khuôn mặt, lương và thu chi của một cửa hàng bán lẻ vào một hệ thống, gồm web quản trị, app iOS/Android cho nhân viên và trang bán hàng riêng có trợ lý AI. Hệ thống khởi đầu là phần mềm nội bộ của CiCi 21 Chùa Láng và nay đã chạy được nhiều cửa hàng.

Kiến trúc sư & lập trình viên chính

S Store — nền tảng quản lý cửa hàng bán lẻ (Web · iOS · Android)

3

Doanh nghiệp đang triển khai

2023

Phát triển từ

189

Tool AI qua MCP

8

AI agent vận hành

Web · iOS · Android

Nền tảng

Vấn đề

CiCi 21 Chùa Láng là cửa hàng phụ kiện thời trang nữ ở Hà Nội. Đơn hàng đã nằm trên KiotViet, còn ca làm, chấm công, lương, lịch vệ sinh kho và thu chi vẫn làm bằng Excel và sổ tay. Cuối tháng phải mất nhiều buổi để tính lương. Mặt hàng sắp hết hay đơn bị lệch thường chỉ được phát hiện khi đã muộn.

Spark Store được viết để xử lý đúng những việc đó. Sau khi chạy ổn ở CiCi, hệ thống được tách thành nền tảng để cửa hàng khác dùng chung hạ tầng mà vẫn có thương hiệu và dữ liệu riêng.

Storefront của CiCi 21 Chùa Láng chạy trên Spark Store
Storefront của CiCi 21 Chùa Láng chạy trên Spark Store

Ai dùng, dùng ở đâu

Người dùngNền tảngCông việc chính
Chủ cửa hàngWeb quản trị và appDoanh thu, lãi lỗ, giá vốn, lương, cổ đông, cấu hình cửa hàng, trợ lý AI
Quản lýWeb và appXếp và duyệt ca, kiểm kho, nhập hàng, duyệt công
Nhân viênApp iOS/AndroidChấm công, đăng ký và đổi ca, xem lương, bán hàng tại quầy, kiểm quầy
Khách hàngTrang bán hàng (web)Xem sản phẩm, hỏi trợ lý AI về hàng và tồn kho, đặt hàng khi cửa hàng mở bán online
Người vận hành nền tảngSpark ConsoleTạo cửa hàng, gắn tên miền, chọn gói, đặt thương hiệu, xem nhật ký

Tính năng

Nhân sự và ca làm

  • Mẫu ca và lịch làm theo tuần. Nhân viên tự đăng ký ca, quản lý duyệt.
  • Chợ ca: nhả ca, nhận ca, đổi ca và "làm hộ một phần" khi đồng nghiệp đến muộn.
  • Chấm công bằng khuôn mặt, GPS trong bán kính cửa hàng hoặc kiosk ghép cặp tại quầy. Có lịch sử và nhật ký kiểm tra ca.
  • Lịch vệ sinh kho dựng theo mẫu và nhân bản được theo tuần. Nhân viên đánh dấu hoàn thành, quản lý duyệt, việc bỏ sót bị ghi phạt.

Lương

  • Kỳ lương tự chốt, có chính sách phạt, ngày lễ và cấu hình lương theo từng người.
  • Nhân viên xem lương tạm tính ngay trên app.

Bán hàng

  • POS trên web và trên app: nhiều đơn nháp cùng lúc, tìm theo mã vạch, chọn biến thể.
  • Nhân viên bán đúng giá niêm yết. Chỉ quản lý được sửa giá, giảm giá hoặc sửa hoá đơn.
  • Đơn bán, trả hàng, mã giảm giá, chương trình khuyến mãi, voucher đối tác.
  • Thanh toán QR động, ngân hàng báo có thì đơn tự xác nhận.

Kho và mua hàng

  • Hàng hoá, đơn vị tính, nhà cung cấp, đơn nhập, trả hàng nhập, kiểm kho, phiếu hư hỏng và phiếu dùng nội bộ.
  • Cảnh báo hàng sắp hết, chỉ tính hàng đang bán dưới định mức.
  • Chủ cửa hàng chỉnh tồn ngay trên app; phiếu chỉnh được đẩy sang KiotViet khi bật đồng bộ chiều đẩy.

Tài chính

  • Phiếu thu chi, quỹ tiền mặt, chi phí, kiểm quầy theo ca.
  • Quản lý cổ đông, quyết toán, báo cáo thuế và chi phí.

Giao tiếp

  • Chat nội bộ theo thời gian thực, thông báo đẩy trên app và qua Telegram.

Mỗi cửa hàng bật hoặc tắt phân hệ theo gói dịch vụ. Hiện có 11 nhóm tính năng: chấm công, xếp ca, vệ sinh, lương, phạt, POS, kho, đồng bộ KiotViet, chatbot, trang chủ storefront và trợ lý AI. Ngoài gói, có thể bật riêng từng tính năng cho một cửa hàng.

App Spark Store

Cửa hàng mẫu trên nền tảng: cùng hệ thống, tên miền và thương hiệu riêng
Cửa hàng mẫu trên nền tảng: cùng hệ thống, tên miền và thương hiệu riêng
  • App viết bằng React Native (Expo, expo-router, NativeWind). Một mã nguồn build ra hai bản: app CiCi và app Spark Store dùng chung cho các cửa hàng SaaS. App đã có trên App Store và CH Play.
  • Người dùng mở app, nhập mã hoặc link cửa hàng rồi đăng nhập bằng Apple, Google hoặc email. Sau khi đăng nhập, giao diện đổi theo màu thương hiệu của cửa hàng đó.
  • Phiên đăng nhập gắn với từng thiết bị và tự gia hạn 30 ngày. Khi mất mạng, app không đăng xuất người dùng.
  • Quyền xem dữ liệu khác nhau theo vai trò. Giá vốn chỉ chủ và quản lý thấy. Nhân viên chỉ mở được hoá đơn mình bán trong ngày. Muốn vào màn kiểm quầy, nhân viên phải có ca hôm nay và đang đứng ở cửa hàng.
  • App có tiếng Anh và tiếng Việt, cập nhật OTA qua EAS Update.

Trợ lý AI và MCP

Trợ lý AI trên storefront: tra sản phẩm, kiểm tra tồn kho, hỏi đáp 24/7
Trợ lý AI trên storefront: tra sản phẩm, kiểm tra tồn kho, hỏi đáp 24/7
  • MCP cho từng cửa hàng. Mỗi cửa hàng có /api/mcp (Streamable HTTP) với 189 tool: lương, ca, chấm công, đơn, kho, POS, thu chi, cổ đông, báo cáo. Chủ cửa hàng tạo khoá API theo quyền để nối Claude, Cursor hoặc agent riêng vào dữ liệu thật của cửa hàng.
  • Ghi dữ liệu phải xác nhận. Ở lần gọi đầu, thao tác ghi quan trọng chỉ mô tả việc sẽ làm. Agent phải gửi lại với confirm: true thì thao tác mới chạy. Mọi phiên và lời gọi được lưu nhật ký 90 ngày.
  • Trợ lý trong app dành cho chủ cửa hàng và quản lý. Trợ lý chỉ đọc dữ liệu: mỗi lần hỏi, hệ thống cấp một khoá ngắn hạn có quyền đọc theo vai trò người hỏi, rồi gọi đúng các tool MCP ở trên. Vì vậy trợ lý không có quyền riêng nào ngoài quyền của người hỏi. Câu trả lời được stream về app qua SignalR.
  • Trợ lý trên trang bán hàng trả lời khách 24/7 về sản phẩm, tồn kho và thông tin cửa hàng.

Kiến trúc

  • Đa cửa hàng. Tenant được xác định theo host của request. Tên miền không khớp cửa hàng nào sẽ không bao giờ trả về dữ liệu của cửa hàng khác. Dữ liệu cách ly bằng Row-Level Security trên PostgreSQL, và mỗi dịch vụ dùng role database với quyền tối thiểu.
  • Tạo cửa hàng không cần thao tác tay. Backend commit Ingress của cửa hàng mới vào repo GitOps qua GitHub API. ArgoCD đồng bộ, cert-manager cấp TLS, và cửa hàng chạy được ngay ở <mã>.store.devbyspark.com.
  • Đăng nhập tập trung qua auth.devbyspark.com. Một tài khoản dùng được cho nhiều cửa hàng và liên kết được một Google, một Apple, một Facebook.

Công nghệ sử dụng

Backend

Công nghệDùng để làm gì, dùng như thế nào
ASP.NET Core (.NET 8)Một solution ra 3 tiến trình: core-api (REST và SignalR), core-worker (job nền, consumer Kafka) và core-gateway (YARP).
Clean ArchitectureSolution chia thành Domain, Application, Contracts, Infrastructure, Api, Worker, Gateway và Tests. Nghiệp vụ nằm ở Domain và Application, không phụ thuộc EF Core hay ASP.NET.
MediatR (CQRS)Mỗi thao tác là một Command hoặc Query riêng. FluentValidation chạy ở pipeline behavior trước khi vào handler. Lỗi nghiệp vụ trả về theo result pattern (ErrorOr), không ném exception.
EF Core + NpgsqlORM cho PostgreSQL. Migration chạy bằng Job PreSync của ArgoCD với một role riêng, chạy xong mới cho bản mới lên.
BackgroundServiceJob nền viết bằng hosted service, không dùng Hangfire hay Quartz: đồng bộ KiotViet theo lịch, chi phí định kỳ, nhắc ca, nhắc chốt kỳ lương, tự chốt kiểm quầy, xử lý phiếu nhập từ ảnh hoá đơn, reset cửa hàng mẫu hằng đêm.
Transactional OutboxSự kiện ghi vào bảng Outbox trong cùng transaction với dữ liệu, rồi tiến trình relay đẩy sang Kafka. Nhờ vậy Kafka có tạm lỗi cũng không mất sự kiện.
YARPReverse proxy đứng trước core-api, gắn header tenant cho mọi request. Đây cũng là chỗ để tách dịch vụ về sau.
Mapster · ClosedXML · QRCoder · BCryptLần lượt dùng để map entity sang DTO, xuất báo cáo Excel, sinh mã QR và băm mật khẩu.

Dữ liệu

Công nghệDùng để làm gì, dùng như thế nào
PostgreSQL + Row-Level SecurityCơ sở dữ liệu chính. Middleware xác định cửa hàng theo Host. Interceptor đặt app.tenant_id khi mở connection và xoá khi trả connection về pool. Policy RLS bật trên mọi bảng thuộc cửa hàng. Ứng dụng chạy bằng role chỉ có quyền đọc ghi dữ liệu, không vượt được RLS; migration dùng role khác.
pgvectorLưu vector khuôn mặt nhân viên kèm tên bộ model, có index HNSW, so khớp bằng cosine. Dùng để xác minh 1:1 khi chấm công trên app và nhận diện 1:N ở kiosk.
MongoDBDữ liệu ghi nhiều, dạng log: lịch sử chatbot, tin nhắn nội bộ, audit log, nhật ký ca, log webhook KiotViet.
RedisTrạng thái, khoá và lệnh huỷ của job đồng bộ KiotViet. Pub/sub đẩy tiến độ đồng bộ lên SignalR. Vé đăng nhập dùng một lần (SSO, đăng nhập QR, liên kết tài khoản). Version quyền để mọi pod làm mới cache quyền cùng lúc. Nonce chống gửi lại cho chữ ký HMAC. Cache câu hỏi thường gặp của chatbot.
KafkaTopic kiotviet.sync: webhook và lịch đồng bộ đẩy sự kiện vào, worker xử lý. Nhờ vậy việc gọi API KiotViet (chậm) không chặn request của người dùng.
Cloudflare R2Ảnh sản phẩm, ảnh chấm công, ảnh vệ sinh kho, hoá đơn nhập. Dữ liệu nhạy cảm nằm ở bucket riêng, chỉ mở được bằng presigned URL ngắn hạn.

Realtime, đăng nhập và tích hợp

Công nghệDùng để làm gì, dùng như thế nào
SignalRMỗi việc một hub: thông báo và buộc đăng xuất, tiến độ đồng bộ, trợ lý AI (stream từng đoạn), chat nội bộ, kiosk chấm công, tự kiểm tra khuôn mặt, màn hình thiết bị và cửa hàng trực tiếp.
JWT + auth.devbyspark.comBackend tự phát JWT và kiểm lại trạng thái tài khoản, phiên đăng nhập ở mỗi request. Google, Apple, Facebook và OTP email đều đi qua trang đăng nhập tập trung. Trang này trả về một vé ngắn hạn, dùng một lần, để đổi lấy phiên kèm PKCE. Web còn đăng nhập được bằng mã QR quét từ app.
spark-paymentDịch vụ thanh toán riêng: .NET 8 Minimal API, EF Core 8, PostgreSQL riêng. Nhận biến động số dư từ SePay, Casso, ApiPay và cổng payOS, VNPay. Khớp giao dịch theo mã đơn, chống trùng khi nhiều nguồn cùng báo một giao dịch, rồi báo về core-api bằng callback ký HMAC. Trang vận hành viết bằng Vue 3 + Naive UI.
Thông báo ngân hàng trên AndroidKênh dự phòng: một máy Android đọc thông báo biến động số dư rồi gửi lên. Mỗi máy có khoá HMAC-SHA256 riêng, nonce lưu trong Redis để chặn gửi lại.
KiotViet API + webhookKéo hàng hoá, đơn và tồn kho qua Kafka; nhận webhook để cập nhật ngay. Chiều đẩy hoá đơn và phiếu chỉnh tồn sang KiotViet đã có, bật theo cấu hình.
Telegram Bot API · Expo Push · SMTPBáo cho quản lý qua Telegram, push thông báo lên app, gửi mã OTP qua email.

AI

Công nghệDùng để làm gì, dùng như thế nào
MCP server tự viếtPOST /api/mcp trên tên miền của từng cửa hàng, JSON-RPC 2.0 qua Streamable HTTP. Bộ 189 tool sinh từ một file manifest. Mỗi tool gọi lại API nội bộ nên dùng chung phân quyền và RLS với web và app. Có khoá ck_ theo cửa hàng, giới hạn tần suất theo khoá, kiểm Origin. Nhật ký giữ 90 ngày, giá trị bí mật được che. Thao tác cần xác nhận sẽ trả về 409 cho tới khi agent gửi lại kèm confirm: true.
SPARK AI GatewayTrợ lý trong app gọi LLM qua Gateway (API kiểu OpenAI). Model trả về tool_calls; core-api tự chạy tool đọc bằng khoá ngắn hạn theo vai trò người hỏi, rồi stream câu trả lời qua SignalR. Một model vision đọc ảnh hoá đơn nhà cung cấp để tạo phiếu nhập.
Face Tracking ServiceDịch vụ Python (FastAPI, ONNX Runtime) lo phần nhận diện khuôn mặt. core-api gọi sang qua HTTP; kiosk và màn tự kiểm tra stream qua WebSocket. Xem trang dự án riêng.

Web quản trị, console và app

Công nghệDùng để làm gì, dùng như thế nào
Next.js 14 (App Router) + MUI 6Web quản trị. Một bản build phục vụ mọi tên miền cửa hàng: middleware gắn X-Tenant-Domain, rewrites chuyển /api sang core-api, nên trình duyệt không gọi thẳng backend. Bảng dữ liệu dùng MUI X DataGrid.
react-hook-form + yup · zustandForm có validate; zustand giữ state cục bộ cho chat nội bộ và chi nhánh đang làm việc.
FullCalendar · ApexCharts · @hello-pangea/dndLịch ca và chấm công, biểu đồ báo cáo, kéo thả để xếp ca.
Mã vạch tự viết · qrcode · @react-pdfBộ mã hoá EAN-13 và Code128 tự viết cho máy in tem nhiệt; QR VietQR in trên hoá đơn; xuất hoá đơn PDF.
getUserMedia + SignalRKiosk chấm công chạy ngay trên trình duyệt: lấy hình từ camera, gửi từng khung hình lên kiosk hub.
Spark Console (Next.js 14 + MUI)Console vận hành nền tảng. Mọi thao tác chạy bằng Server Actions, gọi core-api với JWT trong cookie httpOnly: tạo cửa hàng, gắn tên miền, chọn gói, đặt thương hiệu, bật tắt tính năng, reset cửa hàng mẫu.
React Native + ExpoApp nhân viên. Điều hướng bằng expo-router. Giao diện dùng NativeWind, màu thương hiệu đổi theo cửa hàng qua biến CSS. TanStack Query gọi API, zustand giữ state.
app.config.ts + EASBiến APP_VARIANT đổi bundle id, icon, scheme và ngôn ngữ, nên một mã nguồn build ra 2 app. EAS Build chạy theo profile; EAS Update đẩy bản OTA theo từng channel.
Các module Expoexpo-camera chụp mặt chấm công và quét QR để ghép kiosk. expo-location kiểm geofence với chi nhánh gần nhất. expo-notifications nhận push theo kênh. expo-secure-store giữ token.
Đăng nhập trên appiOS dùng Sign in with Apple native (expo-apple-authentication). Google, và Apple trên Android, mở trang auth.devbyspark.com, nhận mã một lần qua deep link rồi đổi lấy phiên kèm PKCE (expo-crypto).

Kiểm thử và triển khai

Công nghệDùng để làm gì, dùng như thế nào
xUnit · Moq · TestcontainersTest backend. Testcontainers dựng PostgreSQL (có pgvector) và Redis thật để kiểm dữ liệu không rò sang cửa hàng khác qua RLS.
Vitest · Playwright · JestTest cho web, test end-to-end bằng Playwright, Jest cho app.
GitHub Actions → Docker Hub → GitOpsTest hỏng thì không deploy. Build image cho api, worker, gateway, đẩy lên Docker Hub rồi sửa tag trong repo core-gitops. ArgoCD tự đồng bộ lên cluster.
Kubernetes (K3s) + ArgoCDcore-api, worker, gateway, web, console và spark-payment chạy trên cluster chung (xem dự án SPARK Platform).

Kết quả

  • Phát triển từ 2023; app đã có trên App Store và CH Play.
  • Đang triển khai cho 3 doanh nghiệp: cici21chualang.vn, huangcf.store.devbyspark.com, ngoc-tam-cac.pages.dev; cấp SaaS cho cửa hàng mới theo yêu cầu. Cửa hàng mẫu: demo.store.devbyspark.com.
  • CiCi bỏ Excel. Ca làm, chấm công, lịch vệ sinh kho và lương của vài chục nhân sự, quản lý và các chi nhánh được tính tự động; vận hành hằng ngày được tự động hoá bởi đội AI agent.
  • Hàng sắp hết và đơn bán lệch được cảnh báo ngay, không phải chờ đối chiếu sổ cuối ngày.
  • Chủ cửa hàng có báo cáo thuế và chi phí cho cổ đông.

Điểm nổi bật

  • .NET 8, Clean Architecture, CQRS (MediatR): backend cho ca làm, chấm công, lương, bán hàng và kho. Mỗi thao tác là một Command hoặc Query, validate bằng FluentValidation, lưu PostgreSQL qua EF Core.

  • AI agent + MCP: MCP server tự viết (189 tool) dùng chung phân quyền của API; 8 agent chạy theo lịch (báo cáo, CSKH trên Messenger, marketing, HR, kho) gọi Claude bằng tool calling, mọi thao tác ghi phải qua hàng chờ người duyệt.

  • PostgreSQL Row-Level Security: biến hệ thống một cửa hàng thành SaaS đa tenant. Tenant lấy theo tên miền và gắn vào từng kết nối, để database tự lọc dữ liệu của từng cửa hàng.

  • Kafka + Redis: Kafka làm hàng đợi đồng bộ KiotViet, sự kiện ghi qua outbox nên không mất khi lỗi. Redis giữ trạng thái job, khoá và vé đăng nhập một lần.

  • SignalR, Next.js, React Native (Expo): SignalR đẩy realtime thông báo, chat, kiosk chấm công và câu trả lời AI. Web quản trị viết bằng Next.js. Một mã nguồn React Native build ra 2 app iOS/Android.

  • Python / ONNX Runtime + pgvector: dịch vụ nhận diện khuôn mặt cho chấm công; vector khuôn mặt so khớp bằng pgvector.

  • POS offline + phần cứng quầy: bán khi mất mạng (Service Worker + hàng đợi offline), máy hiện QR qua Web Serial, mẫu in hoá đơn kéo thả.

  • Hệ sinh thái dịch vụ: S Pay (thanh toán), S Shipping (vận chuyển), Storefront bán online, Console quản trị nền tảng.

  • Kubernetes (K3s) + ArgoCD: triển khai theo GitOps. Khi tạo cửa hàng mới, backend tự commit Ingress, ArgoCD đồng bộ và cấp TLS.

Hình ảnh

Storefront của CiCi 21 Chùa Láng chạy trên Spark Store
Cửa hàng mẫu trên nền tảng SaaS — cùng hệ thống, tên miền và thương hiệu riêng
Trợ lý AI trên storefront: tra sản phẩm, kiểm tra tồn kho, hỏi đáp 24/7