renolation/retail-nest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

after claude code

Browse Source
This commit is contained in:
Phuoc Nguyen
2025-10-10 16:04:10 +07:00
parent cc53f60bea
commit 6203e8c2ec
109 changed files with 10109 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

245
README.md
View File

@@ -1,98 +1,217 @@
<p align="center">
<a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
</p>
# 🛒 Retail POS Backend API
[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
[circleci-url]: https://circleci.com/gh/nestjs/nest
A comprehensive NestJS REST API backend for the Retail POS Flutter mobile application, providing product management, transaction processing, and offline-sync capabilities.
<p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
<p align="center">
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
<a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
<a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
</p>
<!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
[![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
---
## Description
## 🚀 Quick Start
[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
**See [QUICK_START.md](./QUICK_START.md) for step-by-step setup instructions.**
## Project setup
### Prerequisites
- Node.js 18+
- PostgreSQL 15+
- (Optional) Redis for caching
### Installation
```bash
$ npm install
# 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
```
## Compile and run the project
**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
# Development
npm run start:dev # Start with hot-reload
npm run start:debug # Start with debugger
# watch mode
$ npm run start:dev
# Production
npm run build # Build for production
npm run start:prod # Run production build
# production mode
$ npm run start:prod
# 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
```
## Run tests
---
## 🐳 Docker Deployment
```bash
# unit tests
$ npm run test
# Start all services (PostgreSQL, Redis, API)
docker-compose up -d
# e2e tests
$ npm run test:e2e
# Run migrations
docker-compose exec api npm run migration:run
# test coverage
$ npm run test:cov
# View logs
docker-compose logs -f api
```
## Deployment
---
When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
## 🛣️ API Endpoints
If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
### Authentication
- `POST /api/auth/register` - Register new user
- `POST /api/auth/login` - Login user
- `GET /api/auth/profile` - Get current user (protected)
```bash
$ npm install -g @nestjs/mau
$ mau deploy
### 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
```
With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
---
## Resources
## 🤝 Contributing
Check out a few resources that may come in handy when working with NestJS:
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
- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
---
## Support
## 📝 License
Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
This project is [MIT licensed](LICENSE).
## Stay in touch
---
- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
- Website - [https://nestjs.com](https://nestjs.com/)
- Twitter - [@nestframework](https://twitter.com/nestframework)
## 🆘 Support
## License
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
Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
---
**Built with ❤️ using NestJS**