🇬🇧 English  ·  🇮🇷 فارسی

---

🇬🇧 English

A Point-of-Sale and Inventory Management System split into four independent applications — working together as one.

🏗️ Architecture

                         ┌─────────────────────────┐
                         │      Backend API         │
                         │   Express · Prisma · SQLite│
                         │          :5000            │
                         └────────────┬───────────────┘
                   ┌──────────────────┼──────────────────┐
                   │                  │                  │
         ┌─────────▼────────┐ ┌──────▼───────┐ ┌─────────▼─────────┐
         │   Admin Panel     │ │ Sales System  │ │ Warehouse System   │
         │ React · Vite      │ │  Next.js 16   │ │   Next.js 16       │
         │      :8080        │ │     :3000     │ │       :3001        │
         └───────────────────┘ └───────────────┘ └────────────────────┘

🧮 Backend :5000 Node.js + Express + Prisma + SQLite API, auth, and every database operation. pos-backend/

🛠️ Admin Panel :8080 React + Vite + TanStack Router + shadcn/ui Products, customers, users, invoices, inventory, reports, settlements. rtl-admin-dashboard/

🧾 Sales System :3000 Next.js 16 (App Router) Cart building, invoice generation and printing. invoice-management-system/

📦 Warehouse System :3001 Next.js 16 (App Router) Stock in/out with reasons, low-stock alerts. invoice-inventory-system/

🔑 Login Credentials

Role	Phone	Password
👑 Admin	09121112233	123456
🧾 Sales	Created by Admin	—
📦 Warehouse	Created by Admin	—
🧮 Sales Admin	Created by Admin	—

🎯 Features

🧮 User Management (Admin)

• Create, edit, delete users
• Assign roles: admin, sales, warehouse, sales_admin
• Enable / disable users

📦 Product & Inventory Management

• Create, edit, delete products — optional unique code, barcode support
• Units: Bottle · Carton · Liter, with configurable carton quantity
• Auto-calculated unit & carton pricing
• Stock minimums, in/out-of-stock status
• Add/subtract stock with a logged reason
• Low-stock view and negative-inventory monitoring

🧾 Invoicing (Sales)

• Customer search or instant creation
• Product addition with unit selection, order & carton calculation
• Item-level and total discounts
• Draft registration → invoice printing with product codes
• "Draft" watermark for regular sellers
• Customer's previous debt shown at point of sale

👥 Customers & Settlements

• Purchase history and statistics
• Debt calculation, partial-payment settlement
• Debtor list, payment history, debt adjustment

📊 Reports

• Sales reports — daily / weekly / monthly
• Inventory reports — stock, inbound, outbound
• Top 5 customers
• Seller commission reports (4%)
• Excel & PDF export

👤 Role Permissions

Role	Access
Admin	████████████████████ Full system access
Sales Admin	██████████████░░░░░░ Invoicing + counts + no watermark + view users
Sales	████████░░░░░░░░░░░░ Invoicing only, watermarked
Warehouse	███████░░░░░░░░░░░░░ Inventory only

💰 Currency Rules

   STORED              DISPLAYED            PRINTED
   Rial (IRR)    →     Toman (÷10)    →     Rial, labeled

Carton price = Unit price × Quantity per carton

🔧 Installation

Prerequisites: Node.js 18+, npm or pnpm

# 1. Clone
git clone https://github.com/here-is-leo/pos-system.git
cd pos-system

# 2. Backend — :5000
cd pos-backend
npm install
npx prisma generate
npx prisma migrate dev --name init
npm run dev

# 3. Admin Panel — :8080
cd ../rtl-admin-dashboard
npm install && npm run dev

# 4. Sales System — :3000
cd ../invoice-management-system
npm install && npm run dev

# 5. Warehouse System — :3001
cd ../invoice-inventory-system
npm install && npm run dev

Backend .env:

DATABASE_URL="file:./dev.db"
JWT_SECRET="your-secret-key"
PORT=5000

Admin .env:

VITE_API_URL="http://localhost:5000"

📋 Key API Endpoints

Method	Endpoint	Description
POST	/api/auth/login	User login
GET	/api/products	Get products
POST	/api/products	Create product
GET	/api/customers	Get customers
GET	/api/invoices	Get invoices
POST	/api/invoices	Create invoice
POST	/api/invoices/:id/finalize	Finalize invoice
GET	/api/inventory	Get inventory
POST	/api/inventory/add	Add stock
POST	/api/inventory/subtract	Subtract stock
GET	/api/customers/with-debt	Customers with debt
POST	/api/payments	Record payment

🛠️ Tech Stack

Layer	Technology
Backend	Node.js + Express
Database	SQLite via Prisma ORM
Admin	React + Vite + TanStack Router
Sales / Warehouse	Next.js 16 (App Router)
UI	Tailwind CSS + shadcn/ui
Icons	Lucide React
Charts	Recharts
Export	XLSX, jsPDF

🔐 Security

• 🔑 JWT authentication (7-day expiry)
• 🔒 bcrypt password hashing
• 🚦 Rate limiting (brute-force protection)
• 🧩 Captcha after 3 failed attempts
• 🛡️ Role-based access control
• 🌐 CORS restricted to allowed domains

🎨 UI/UX

• Light mode with subtle colors
• Fully responsive — mobile & desktop
• Collapsible sidebar, smooth animations
• Vazirmatn font, complete RTL support

🐛 Troubleshooting

Port conflicts

npx kill-port 5000

Prisma errors

npx prisma generate
npx prisma migrate dev

Dependency issues

rm -rf node_modules
npm install

CORS errors

• Check VITE_API_URL in the admin .env
• Ensure the backend is running

👥 Contributing

1. Fork the repository
2. git checkout -b feature/AmazingFeature
3. git commit -m 'Add AmazingFeature'
4. git push origin feature/AmazingFeature
5. Open a Pull Request

Coding standards: TypeScript · ESLint · meaningful commits · comments on complex logic · updated docs

📞 Contact & Support

👤 Developer	Ilya Farahani
📧 Email	ilyafarahanii@gmail.com
🐙 GitHub	@here-is-leo
📦 Repository	pos-system

📜 License

Licensed under the MIT License — see LICENSE.

---

🇮🇷 نسخه فارسی

یک سیستم فروش و مدیریت انبار که از چهار اپلیکیشن مستقل تشکیل شده — اما همگی با هم کار می‌کنند.

🏗️ معماری سیستم

                         ┌─────────────────────────┐
                         │          بک‌اند          │
                         │  Express · Prisma · SQLite│
                         │          :5000            │
                         └────────────┬───────────────┘
                   ┌──────────────────┼──────────────────┐
                   │                  │                  │
         ┌─────────▼────────┐ ┌──────▼───────┐ ┌─────────▼─────────┐
         │     پنل ادمین     │ │ سیستم فروشنده │ │  سیستم انباردار    │
         │ React · Vite      │ │  Next.js 16   │ │   Next.js 16       │
         │      :8080        │ │     :3000     │ │       :3001        │
         └───────────────────┘ └───────────────┘ └────────────────────┘

🧮 بک‌اند :5000 Node.js + Express + Prisma + SQLite مدیریت API، احراز هویت و تمام عملیات دیتابیس. pos-backend/

🛠️ پنل ادمین :8080 React + Vite + TanStack Router + shadcn/ui محصولات، مشتریان، کاربران، فاکتورها، موجودی، گزارش‌ها، تسویه‌حساب. rtl-admin-dashboard/

🧾 سیستم فروشنده :3000 Next.js 16 (App Router) ساخت سبد خرید، صدور و چاپ فاکتور. invoice-management-system/

📦 سیستم انباردار :3001 Next.js 16 (App Router) ورود/خروج موجودی با دلیل، هشدار کمبود موجودی. invoice-inventory-system/

🔑 اطلاعات ورود

نقش	تلفن	رمز عبور
👑 ادمین	09121112233	123456
🧾 فروشنده	ساخته‌شده توسط ادمین	—
📦 انباردار	ساخته‌شده توسط ادمین	—
🧮 فروش (ادمین)	ساخته‌شده توسط ادمین	—

🎯 قابلیت‌ها

🧮 مدیریت کاربران (ادمین)

• ایجاد، ویرایش، حذف کاربران
• تعیین نقش‌ها: admin, sales, warehouse, sales_admin
• فعال/غیرفعال کردن کاربران

📦 مدیریت محصولات و موجودی

• ایجاد، ویرایش، حذف محصولات — کد یکتا (اختیاری)، پشتیبانی بارکد
• واحدها: بطری · کارتن · لیتر، با تعداد قابل تنظیم در کارتن
• قیمت واحد و کارتن به‌صورت خودکار محاسبه می‌شود
• حداقل موجودی، وضعیت موجود/ناموجود
• افزودن/کسر موجودی همراه با ثبت دلیل
• نمایش کالاهای کم‌موجود و موجودی منفی

🧾 صدور فاکتور (فروشنده)

• جستجوی مشتری یا ایجاد فوری
• افزودن کالا با انتخاب واحد، محاسبه سفارش و کارتن
• تخفیف آیتمی و کلی
• ثبت پیش‌نویس ← چاپ فاکتور با کد کالا
• واترمارک «پیش‌نویس» برای فروشندگان عادی
• نمایش بدهی قبلی مشتری در لحظه فروش

👥 مشتریان و تسویه‌حساب

• تاریخچه خرید و آمار
• محاسبه بدهی، تسویه با پرداخت جزئی
• لیست بدهکاران، تاریخچه پرداخت، اصلاح بدهی

📊 گزارش‌ها

• گزارش فروش — روزانه / هفتگی / ماهانه
• گزارش انبار — موجودی، ورود، خروج
• ۵ مشتری برتر
• گزارش کمیسیون فروشنده (۴٪)
• خروجی Excel و PDF

👤 سطح دسترسی نقش‌ها

نقش	دسترسی
ادمین	████████████████████ دسترسی کامل به سیستم
فروش (ادمین)	██████████████░░░░░░ فاکتور + آمار + بدون واترمارک + دیدن کاربران
فروشنده	████████░░░░░░░░░░░░ فقط فاکتور، واترمارک‌دار
انباردار	███████░░░░░░░░░░░░░ فقط موجودی

💰 قوانین واحد پول

   ذخیره‌شده             نمایش روی صفحه         فاکتور چاپی
   ریال          ←       تومان (÷۱۰)      ←      ریال، با برچسب

قیمت کارتن = قیمت هر واحد × تعداد در کارتن

🔧 نصب و راه‌اندازی

پیش‌نیازها: Node.js 18+، npm یا pnpm

# ۱. کلون کردن مخزن
git clone https://github.com/here-is-leo/pos-system.git
cd pos-system

# ۲. بک‌اند — :5000
cd pos-backend
npm install
npx prisma generate
npx prisma migrate dev --name init
npm run dev

# ۳. پنل ادمین — :8080
cd ../rtl-admin-dashboard
npm install && npm run dev

# ۴. سیستم فروشنده — :3000
cd ../invoice-management-system
npm install && npm run dev

# ۵. سیستم انباردار — :3001
cd ../invoice-inventory-system
npm install && npm run dev

بک‌اند .env:

DATABASE_URL="file:./dev.db"
JWT_SECRET="your-secret-key"
PORT=5000

ادمین .env:

VITE_API_URL="http://localhost:5000"

📋 APIهای کلیدی

متد	مسیر	توضیح
POST	/api/auth/login	ورود کاربر
GET	/api/products	دریافت محصولات
POST	/api/products	ایجاد محصول
GET	/api/customers	دریافت مشتریان
GET	/api/invoices	دریافت فاکتورها
POST	/api/invoices	ایجاد فاکتور
POST	/api/invoices/:id/finalize	نهایی‌سازی فاکتور
GET	/api/inventory	دریافت موجودی
POST	/api/inventory/add	افزودن موجودی
POST	/api/inventory/subtract	کسر موجودی
GET	/api/customers/with-debt	مشتریان با بدهی
POST	/api/payments	ثبت پرداخت

🛠️ تکنولوژی‌های استفاده‌شده

بخش	تکنولوژی
بک‌اند	Node.js + Express
دیتابیس	SQLite از طریق Prisma ORM
ادمین	React + Vite + TanStack Router
فروشنده / انباردار	Next.js 16 (App Router)
UI	Tailwind CSS + shadcn/ui
آیکون‌ها	Lucide React
نمودار	Recharts
خروجی	XLSX, jsPDF

🔐 ویژگی‌های امنیتی

• 🔑 احراز هویت JWT (انقضای ۷ روز)
• 🔒 هش کردن رمز عبور با bcrypt
• 🚦 محدودیت درخواست (محافظت در برابر Brute Force)
• 🧩 کپچا پس از ۳ تلاش ناموفق
• 🛡️ کنترل دسترسی مبتنی بر نقش
• 🌐 محدودیت CORS به دامنه‌های مجاز

🎨 طراحی UI/UX

• لایت مود با رنگ‌های ملایم
• کاملاً ریسپانسیو — موبایل و دسکتاپ
• سایدبار قابل جمع‌شدن، انیمیشن‌های روان
• فونت وزیرمتن، پشتیبانی کامل از راست‌چینی

🐛 عیب‌یابی

تداخل پورت

npx kill-port 5000

خطاهای Prisma

npx prisma generate
npx prisma migrate dev

مشکلات وابستگی‌ها

rm -rf node_modules
npm install

خطاهای CORS

• آدرس VITE_API_URL را در .env پنل ادمین بررسی کنید
• مطمئن شوید بک‌اند در حال اجراست

👥 مشارکت در توسعه

۱. مخزن را Fork کنید
۲. git checkout -b feature/AmazingFeature
۳. git commit -m 'Add AmazingFeature'
۴. git push origin feature/AmazingFeature
۵. یک Pull Request باز کنید

استانداردهای کدنویسی: TypeScript · رعایت ESLint · پیام‌های commit معنادار · کامنت برای منطق‌های پیچیده · به‌روزرسانی مستندات

📞 اطلاعات تماس و پشتیبانی

👤 توسعه‌دهنده	ایلیا فراهانی
📧 ایمیل	ilyafarahanii@gmail.com
🐙 گیت‌هاب	@here-is-leo
📦 مخزن پروژه	pos-system

📜 لایسنس

این پروژه تحت مجوز MIT منتشر شده است — برای جزئیات به LICENSE مراجعه کنید.

---

ساخته‌شده با 🧡 توسط ایلیا فراهانی