TheSMS — Point of Sale & Inventory Management System

Phần mềm quản lý bán hàng và kho hàng dành cho doanh nghiệp vừa và nhỏ, chạy offline trên máy tính để bàn.

Mục lục

Giới thiệu
Tính năng
Kiến trúc hệ thống
Yêu cầu hệ thống
Cài đặt môi trường phát triển
Cấu hình
Lệnh thông dụng
Cấu trúc thư mục
Database & Migration
Build & Đóng gói
Đóng góp
Quy ước code

Giới thiệu

TheSMS (v1.1.3) là ứng dụng desktop ERP dành cho doanh nghiệp bán lẻ và bán sỉ. Phần mềm hoạt động hoàn toàn offline, lưu trữ dữ liệu nội bộ qua SQLite, được đóng gói thành file .exe / .dmg / .AppImage thông qua Electron.

Tính năng

Phân hệ	Mô tả
POS — Bán hàng	Giao diện bán hàng nhanh, hỗ trợ bán lẻ / sỉ / online / đặt trước
Đơn hàng & Hóa đơn	Quản lý vòng đời đơn hàng, xuất hóa đơn, theo dõi công nợ
Kho hàng	Nhập hàng, quản lý nhiều kho, vị trí kho, kiểm kê
Sản phẩm	Danh mục, thuộc tính, đơn vị tính (UOM), barcode, ảnh sản phẩm
Đối tác	Khách hàng, nhà cung cấp, nhóm khách hàng, công nợ
Bảng giá & Khuyến mãi	Bảng giá linh hoạt, chương trình khuyến mãi
Thanh toán	Tiền mặt, chuyển khoản, MoMo, ZaloPay, COD, công nợ
Tài chính	Thu chi, phụ phí, báo cáo tài chính tổng quan
Báo cáo	Báo cáo doanh thu, tồn kho, sản phẩm
In ấn	In hóa đơn nhiệt (thermal printer), mẫu in tùy chỉnh
Người dùng	Phân quyền RBAC, quản lý tài khoản
Cài đặt	Cấu hình công ty, tồn kho, phương thức thanh toán

Kiến trúc hệ thống

┌──────────────────────────────────────────────────┐
│                  Electron Shell                  │
│  ┌─────────────────┐    ┌───────────────────────┐│
│  │  Frontend        │    │  Backend (Main Process)││
│  │  Vue 3 + Vite    │◄──►│  Express.js API       ││
│  │  Tailwind CSS    │IPC │  Prisma ORM           ││
│  │  Vue Router      │    │  SQLite Database      ││
│  └─────────────────┘    └───────────────────────┘│
└──────────────────────────────────────────────────┘

Frontend: Vue 3 (Composition API) + Vite + Tailwind CSS, chạy trong Renderer Process.
Backend: Express.js server chạy trong Main Process, giao tiếp với Frontend qua IPC và HTTP.
ORM: Prisma + better-sqlite3 — truy vấn type-safe, migration có version.
Đóng gói: electron-builder tạo installer cho Windows / macOS / Linux.

Yêu cầu hệ thống

Thành phần	Phiên bản tối thiểu
Node.js	>= 18.x (LTS)
npm	>= 9.x
Python	>= 3.x (cần cho `better-sqlite3` native build)
Windows Build Tools	Khi build trên Windows: `npm i -g windows-build-tools`
Git	Bất kỳ phiên bản hiện đại

Cài đặt môi trường phát triển

1. Clone repository

git clone https://github.com/nguyenminh121/TheSMS.git
cd TheSMS

2. Cài đặt dependencies

npm install

Lệnh postinstall sẽ tự động chạy electron-builder install-app-deps và rebuild better-sqlite3 cho đúng phiên bản Electron.

3. Khởi tạo Database

# Đẩy schema lên SQLite và seed dữ liệu mẫu
npm run db:setup

Hoặc từng bước:

npm run prisma:push        # Đẩy schema (không tạo migration file)
npm run prisma:seed        # Seed dữ liệu mẫu

4. Chạy môi trường dev

npm run dev

Ứng dụng Electron sẽ khởi động với Hot Reload cho cả Frontend và Backend.

Cấu hình

Biến môi trường

Tạo file .env tại thư mục gốc (tham khảo .env.example nếu có):

DATABASE_URL="file:./database/dev.db"

Trong production, đường dẫn database sẽ được override tự động bởi src/backend/config/database.js sang thư mục userData của hệ điều hành.

Cấu hình công ty

File storage/user_data/config/company.json lưu thông tin công ty hiển thị trên hóa đơn:

{
  "name": "CÔNG TY TNHH ABC",
  "address": "123 Đường ABC, Quận 1, TP.HCM",
  "phone": "0909 123 456",
  "email": "info@company.com",
  "taxCode": "0123456789",
  "website": "https://www.company.com",
  "logo": null
}

Lệnh thông dụng

# Phát triển
npm run dev                    # Chạy ứng dụng dev mode

# Code quality
npm run lint                   # Kiểm tra linting (ESLint)
npm run format                 # Format code (Prettier)

# Prisma / Database
npm run prisma:generate        # Tạo lại Prisma Client từ schema
npm run prisma:migrate:dev     # Tạo migration mới trong dev
npm run prisma:migrate         # Áp dụng migration (deploy)
npm run prisma:migrate:reset   # Reset toàn bộ database (cẩn thận!)
npm run prisma:migrate:status  # Xem trạng thái migration
npm run prisma:push            # Đẩy schema trực tiếp (không migration)
npm run prisma:seed            # Seed dữ liệu mẫu

# Test in ấn
npm run test:printer           # Test kết nối máy in nhiệt
npm run test:print             # In thử ngay lập tức

# Build
npm run build:win              # Build installer Windows (x64)
npm run build:win:portable     # Build portable Windows
npm run build:mac              # Build installer macOS
npm run build:linux            # Build installer Linux
npm run build:all              # Build tất cả nền tảng

Cấu trúc thư mục

TheSMS/
├── database/
│   ├── schema.prisma          # Schema database chính
│   ├── migrations/            # Lịch sử migration
│   ├── seed.js                # Entry point seed
│   ├── seeders/               # Dữ liệu mẫu theo module
│   └── template.db            # Template DB đóng gói vào app
│
├── scripts/
│   ├── build-database-template.js
│   ├── prisma-migrate.js
│   └── prisma-seed.js
│
├── src/
│   ├── backend/               # Main Process — Express API + Business Logic
│   │   ├── config/            # Cấu hình database, paths
│   │   ├── controllers/       # Route handlers (MVC Controller)
│   │   ├── middlewares/       # Auth, upload middleware
│   │   ├── routes/            # Định nghĩa API routes
│   │   ├── services/          # Business logic layer
│   │   ├── ipc/               # IPC handlers (Electron IPC)
│   │   ├── utils/             # Helpers: logger, printer, storage...
│   │   ├── server.js          # Khởi tạo Express server
│   │   └── index.js           # Entry point Main Process
│   │
│   ├── frontend/              # Renderer Process — Vue 3 App
│   │   └── src/
│   │       ├── api/           # Axios API client
│   │       ├── components/    # UI components dùng chung
│   │       ├── composables/   # Vue composables (useXxx)
│   │       ├── layouts/       # Layout: header, sidebar, footer
│   │       ├── router/        # Vue Router
│   │       ├── store/         # Global state
│   │       ├── utils/         # Utility functions
│   │       └── views/         # Các màn hình theo phân hệ
│   │           ├── auth/
│   │           ├── sales/
│   │           ├── products/
│   │           ├── stock-management/
│   │           ├── invoices/
│   │           ├── partners/
│   │           ├── finance/
│   │           ├── pricing/
│   │           ├── payments/
│   │           ├── warehouses/
│   │           ├── reports/
│   │           ├── users/
│   │           └── settings/
│   │
│   └── preload/
│       └── index.js           # Preload script (bridge IPC)
│
├── storage/
│   └── user_data/
│       └── config/
│           └── company.json   # Thông tin công ty
│
├── electron.vite.config.js    # Cấu hình electron-vite
├── electron-builder.yml       # Cấu hình đóng gói
├── package.json
└── tailwind.config.js

Database & Migration

TheSMS sử dụng Prisma làm ORM với SQLite (better-sqlite3). Schema được định nghĩa tại database/schema.prisma.

Workflow khi thay đổi schema

# 1. Sửa database/schema.prisma

# 2. Tạo migration file mới
npm run prisma:migrate:dev

# 3. Prisma Client tự động regenerate sau migrate
# Hoặc chủ động chạy:
npm run prisma:generate

Các module chính trong schema

Model	Mô tả
`User`, `Role`	Người dùng, phân quyền RBAC
`Product`, `Category`, `Attribute`	Sản phẩm, danh mục, thuộc tính
`UOM`, `UnitType`	Đơn vị tính, quy đổi
`Order`, `OrderItem`	Đơn hàng
`Invoice`, `InvoiceItem`	Hóa đơn
`Import`, `ImportItem`	Phiếu nhập kho
`Stock`, `StockMovement`	Tồn kho, lịch sử xuất nhập
`Warehouse`, `WarehouseLocation`	Kho hàng, vị trí kho
`Customer`, `CustomerGroup`	Khách hàng, nhóm
`Supplier`	Nhà cung cấp
`Payment`	Thanh toán
`PriceList`	Bảng giá
`Promotion`	Khuyến mãi
`Surcharge`	Phụ phí
`BusinessExpense`	Chi phí kinh doanh

Build & Đóng gói

Windows

npm run build:win          # Tạo file installer .exe (NSIS)
npm run build:win:portable # Tạo file portable .exe (không cần cài đặt)

macOS

npm run build:mac          # Tạo file .dmg

Cần chạy trên máy macOS hoặc macOS VM. Cần Apple Developer Certificate để notarize.

Linux

npm run build:linux        # Tạo file .AppImage / .deb

Lưu ý build

better-sqlite3 là native module, cần được rebuild cho đúng phiên bản Electron khi build.
Prisma Client được generate trước khi build (prisma generate).
database/template.db được đóng gói vào app — đây là database trống dùng cho lần chạy đầu tiên.

Đóng góp

Chào mừng mọi đóng góp! Vui lòng đọc kỹ hướng dẫn dưới đây trước khi tạo Pull Request.

Quy trình đóng góp

Fork repository về tài khoản của bạn.

Tạo branch mới từ main:

git checkout -b feat/ten-tinh-nang
# hoặc
git checkout -b fix/ten-bug

Thực hiện thay đổi và tuân thủ Quy ước code.

Commit theo Conventional Commits:

git commit -m "feat(sales): thêm tính năng đặt hàng trước"
git commit -m "fix(invoice): sửa lỗi tính tổng tiền sai"
git commit -m "refactor(product): tách logic UOM ra service"

Push lên fork của bạn:
```
git push origin feat/ten-tinh-nang
```
Tạo Pull Request vào branch main của repo gốc.

Loại đóng góp

Loại	Mô tả
`feat`	Tính năng mới
`fix`	Sửa bug
`refactor`	Tái cấu trúc code (không thêm tính năng, không sửa bug)
`style`	Thay đổi giao diện, CSS
`docs`	Cập nhật tài liệu
`chore`	Cấu hình build, dependencies
`perf`	Cải thiện hiệu năng

Tạo Issue

Trước khi bắt đầu làm một tính năng lớn, hãy tạo Issue để thảo luận. Bao gồm:

Mô tả rõ vấn đề / tính năng
Lý do cần thiết (business case)
Đề xuất hướng thực hiện (nếu có)

Quy ước code

Chung

Dùng ESLint + Prettier — chạy npm run lint và npm run format trước khi commit.
Không commit file .env, *.db, hay file nhạy cảm.
Tên biến / hàm: camelCase. Tên class / component: PascalCase. Hằng số: UPPER_SNAKE_CASE.

Backend (Express / Node.js)

Mỗi phân hệ có đúng một controller, một service, một route.
Business logic nằm trong services/, không nằm trong controllers/.
Truy vấn database chỉ trong services/ — không dùng Prisma trực tiếp trong controller.
Luôn dùng try/catch và trả về lỗi chuẩn: { success: false, message: '...' }.

// Ví dụ response chuẩn
res.status(200).json({ success: true, data: result })
res.status(400).json({ success: false, message: 'Lỗi validate' })

Frontend (Vue 3)

Dùng Composition API (<script setup>) — không dùng Options API.
Logic tái sử dụng đặt trong composables/useXxx.js.
Gọi API qua src/frontend/src/api/index.js — không dùng axios trực tiếp trong component.
Tên component: PascalCase. Tên file component: PascalCase.vue.
Tên view (route): XxxView.vue.

Database / Prisma

Mỗi thay đổi schema phải có migration (npm run prisma:migrate:dev).
Tên migration ngắn gọn, mô tả đúng thay đổi: add_product_images, update_order_status.
Giá trị tiền tệ dùng Decimal, không dùng Float.
Enum cho các trạng thái — không dùng chuỗi tự do.

Tác giả

Nguyen Minh — ngthminh121@gmail.com — ngminh.io.vn

TheSMS v1.1.3 — Built with Electron + Vue 3 + Prisma + SQLite

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.vscode		.vscode
database		database
markdown		markdown
resources		resources
sample_data		sample_data
scripts		scripts
src		src
storage		storage
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.yaml		.prettierrc.yaml
LICENSE		LICENSE
README.md		README.md
dev-app-update.yml		dev-app-update.yml
electron-builder.yml		electron-builder.yml
electron.vite.config.mjs		electron.vite.config.mjs
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js

Folders and files

Latest commit

History

Repository files navigation