218 lines
5.7 KiB
Markdown
218 lines
5.7 KiB
Markdown
# 🛒 Retail POS Backend API
|
|
|
|
A comprehensive NestJS REST API backend for the Retail POS Flutter mobile application, providing product management, transaction processing, and offline-sync capabilities.
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
**See [QUICK_START.md](./QUICK_START.md) for step-by-step setup instructions.**
|
|
|
|
### Prerequisites
|
|
- Node.js 18+
|
|
- PostgreSQL 15+
|
|
- (Optional) Redis for caching
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Setup database
|
|
createdb retail_pos
|
|
|
|
# Update .env with your PostgreSQL credentials
|
|
# DB_USERNAME, DB_PASSWORD, DB_DATABASE
|
|
|
|
# Run migrations
|
|
npm run migration:run
|
|
|
|
# Seed sample data (optional)
|
|
npm run seed:run
|
|
|
|
# Start development server
|
|
npm run start:dev
|
|
```
|
|
|
|
**Access the API:**
|
|
- API: http://localhost:3000/api
|
|
- Swagger Docs: http://localhost:3000/api/docs
|
|
|
|
---
|
|
|
|
## 📦 Features
|
|
|
|
- ✅ **Authentication**: JWT-based auth with role-based access control
|
|
- ✅ **Products API**: CRUD operations with search and filtering
|
|
- ✅ **Categories API**: Category management with product relations
|
|
- ✅ **Transactions API**: POS transaction processing with stock management
|
|
- ✅ **Sync API**: Offline-first mobile sync capabilities
|
|
- ✅ **User Management**: Multi-role user system (Admin, Manager, Cashier)
|
|
- ✅ **API Documentation**: Auto-generated Swagger/OpenAPI docs
|
|
- ✅ **Docker Support**: Production-ready containerization
|
|
|
|
---
|
|
|
|
## 🏗️ Tech Stack
|
|
|
|
- **Framework**: NestJS 11
|
|
- **Language**: TypeScript
|
|
- **Database**: PostgreSQL 15 with TypeORM
|
|
- **Cache**: Redis (optional, uses in-memory by default)
|
|
- **Authentication**: JWT with Passport
|
|
- **Validation**: class-validator, class-transformer
|
|
- **Documentation**: Swagger/OpenAPI
|
|
|
|
---
|
|
|
|
## 📚 Documentation
|
|
|
|
- **[Quick Start Guide](./QUICK_START.md)** - Get up and running in 3 steps
|
|
- **[Setup Guide](./SETUP_COMPLETE.md)** - Complete setup documentation
|
|
- **[Database Guide](./docs/DATABASE_SETUP.md)** - Database schema and migrations
|
|
- **[Auth System](./docs/AUTH_SYSTEM.md)** - Authentication & authorization details
|
|
- **[API Documentation](http://localhost:3000/api/docs)** - Interactive Swagger UI (when running)
|
|
|
|
---
|
|
|
|
## 🔐 Default Credentials
|
|
|
|
After running `npm run seed:run`:
|
|
|
|
| Role | Email | Password |
|
|
|------|-------|----------|
|
|
| Admin | admin@retailpos.com | Admin123! |
|
|
| Manager | manager@retailpos.com | Manager123! |
|
|
| Cashier | cashier@retailpos.com | Cashier123! |
|
|
|
|
---
|
|
|
|
## 📋 Available Scripts
|
|
|
|
```bash
|
|
# Development
|
|
npm run start:dev # Start with hot-reload
|
|
npm run start:debug # Start with debugger
|
|
|
|
# Production
|
|
npm run build # Build for production
|
|
npm run start:prod # Run production build
|
|
|
|
# Database
|
|
npm run migration:run # Run migrations
|
|
npm run migration:revert # Revert last migration
|
|
npm run seed:run # Seed database
|
|
|
|
# Testing
|
|
npm run test # Run unit tests
|
|
npm run test:e2e # Run E2E tests
|
|
npm run test:cov # Test coverage
|
|
|
|
# Code Quality
|
|
npm run lint # Lint code
|
|
npm run format # Format with Prettier
|
|
```
|
|
|
|
---
|
|
|
|
## 🐳 Docker Deployment
|
|
|
|
```bash
|
|
# Start all services (PostgreSQL, Redis, API)
|
|
docker-compose up -d
|
|
|
|
# Run migrations
|
|
docker-compose exec api npm run migration:run
|
|
|
|
# View logs
|
|
docker-compose logs -f api
|
|
```
|
|
|
|
---
|
|
|
|
## 🛣️ API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/auth/register` - Register new user
|
|
- `POST /api/auth/login` - Login user
|
|
- `GET /api/auth/profile` - Get current user (protected)
|
|
|
|
### Products
|
|
- `GET /api/products` - List products (public)
|
|
- `POST /api/products` - Create product (Admin/Manager)
|
|
- `PUT /api/products/:id` - Update product (Admin/Manager)
|
|
- `DELETE /api/products/:id` - Delete product (Admin)
|
|
|
|
### Categories
|
|
- `GET /api/categories` - List categories (public)
|
|
- `POST /api/categories` - Create category (Admin/Manager)
|
|
- `PUT /api/categories/:id` - Update category (Admin/Manager)
|
|
- `DELETE /api/categories/:id` - Delete category (Admin)
|
|
|
|
### Transactions
|
|
- `GET /api/transactions` - List transactions (Cashier+)
|
|
- `POST /api/transactions` - Create transaction (Cashier+)
|
|
- `GET /api/transactions/stats` - Get statistics (Manager+)
|
|
|
|
### Sync
|
|
- `POST /api/sync` - Sync all data for offline mobile (Cashier+)
|
|
- `GET /api/sync/status` - Get sync status (Cashier+)
|
|
|
|
**For full API documentation, visit:** http://localhost:3000/api/docs
|
|
|
|
---
|
|
|
|
## 🗂️ Project Structure
|
|
|
|
```
|
|
retail-nest/
|
|
├── src/
|
|
│ ├── common/ # Global utilities, guards, interceptors
|
|
│ ├── config/ # Configuration modules
|
|
│ ├── database/ # Migrations, seeds, data source
|
|
│ ├── modules/
|
|
│ │ ├── auth/ # Authentication module
|
|
│ │ ├── users/ # User management
|
|
│ │ ├── products/ # Product API
|
|
│ │ ├── categories/ # Category API
|
|
│ │ ├── transactions/ # Transaction API
|
|
│ │ └── sync/ # Mobile sync API
|
|
│ ├── app.module.ts
|
|
│ └── main.ts
|
|
├── test/ # Unit & E2E tests
|
|
├── docs/ # Additional documentation
|
|
├── .env # Environment variables
|
|
├── docker-compose.yml # Docker stack configuration
|
|
└── package.json
|
|
```
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
This is a retail POS backend project. Follow these guidelines:
|
|
1. Follow NestJS best practices
|
|
2. Write tests for new features
|
|
3. Update documentation as needed
|
|
4. Use conventional commits
|
|
|
|
---
|
|
|
|
## 📝 License
|
|
|
|
This project is [MIT licensed](LICENSE).
|
|
|
|
---
|
|
|
|
## 🆘 Support
|
|
|
|
For issues and questions:
|
|
- Check [QUICK_START.md](./QUICK_START.md) for common issues
|
|
- Review [docs/](./docs/) for detailed documentation
|
|
- Check Swagger UI at http://localhost:3000/api/docs
|
|
|
|
---
|
|
|
|
**Built with ❤️ using NestJS**
|