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

first commit

Browse Source
This commit is contained in:
Phuoc Nguyen
2025-10-10 15:04:45 +07:00
commit cc53f60bea
22 changed files with 14651 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

910
claude.md Normal file
View File

@@ -0,0 +1,910 @@
# NestJS Retail POS Backend API Expert Guidelines
## 🎯 Backend Overview
A robust NestJS-based REST API backend for the Retail POS Flutter application, providing product management, category organization, transaction processing, and user authentication with offline-sync capabilities.
---
## 🤖 SUBAGENT DELEGATION SYSTEM 🤖
**CRITICAL: BE PROACTIVE WITH SUBAGENTS! YOU HAVE SPECIALIZED EXPERTS AVAILABLE!**
### 🚨 DELEGATION MINDSET
**Instead of thinking "I'll handle this myself"** **Think: "Which specialist is BEST suited for this task?"**
### 📋 AVAILABLE SPECIALISTS
You have access to these expert subagents - USE THEM PROACTIVELY:
#### 🌐 **nestjs-api-expert**
- **MUST BE USED for**: Controllers, DTOs, REST endpoints, request/response handling, validation
- **Triggers**: "API endpoint", "controller", "DTO", "validation", "REST", "route"
#### 🗄️ **nestjs-database-expert**
- **MUST BE USED for**: TypeORM entities, database schema, migrations, queries, relationships
- **Triggers**: "database", "entity", "migration", "query", "TypeORM", "Prisma", "PostgreSQL"
#### 🏗️ **nestjs-architecture-expert**
- **MUST BE USED for**: Module structure, dependency injection, services, clean architecture
- **Triggers**: "architecture", "module", "service", "dependency injection", "structure"
#### 🔐 **nestjs-auth-expert**
- **MUST BE USED for**: JWT authentication, guards, security, authorization, user management
- **Triggers**: "auth", "JWT", "guard", "security", "login", "authentication"
#### ⚡ **nestjs-performance-expert**
- **MUST BE USED for**: Caching, query optimization, rate limiting, performance tuning
- **Triggers**: "performance", "cache", "Redis", "optimization", "slow", "rate limit"
### 🎯 DELEGATION STRATEGY
**BEFORE starting ANY task, ASK YOURSELF:**
1. "Which of my specialists could handle this better?"
2. "Should I break this into parts for different specialists?"
3. "Would a specialist complete this faster and better?"
### 💼 WORK BALANCE RECOMMENDATION:
- **Simple Tasks (20%)**: Handle independently - quick fixes, minor updates
- **Complex Tasks (80%)**: Delegate to specialists for expert-level results
### 🔧 HOW TO DELEGATE
```
# Explicit delegation examples:
> Use the nestjs-api-expert to create the products CRUD endpoints
> Have the nestjs-database-expert design the transaction entity relationships
> Ask the nestjs-architecture-expert to structure the sync module
> Use the nestjs-auth-expert to implement JWT authentication
> Have the nestjs-performance-expert optimize product queries with caching
```
---
## NestJS Best Practices
- Use TypeScript with strict mode enabled
- Implement modular architecture with feature-based organization
- Follow dependency injection patterns with NestJS IoC
- Use DTOs with class-validator for request validation
- Implement proper error handling with exception filters
- Use TypeORM for database operations
- Follow RESTful API design principles
- Implement comprehensive API documentation with Swagger
- Use environment variables for configuration
- Write unit and e2e tests for all endpoints
## Project Structure
```
src/
common/
decorators/
current-user.decorator.ts
roles.decorator.ts
public.decorator.ts
dto/
pagination.dto.ts
api-response.dto.ts
filters/
http-exception.filter.ts
all-exceptions.filter.ts
guards/
jwt-auth.guard.ts
roles.guard.ts
interceptors/
logging.interceptor.ts
transform.interceptor.ts
cache.interceptor.ts
pipes/
validation.pipe.ts
interfaces/
pagination.interface.ts
utils/
helpers.ts
formatters.ts
config/
app.config.ts
database.config.ts
jwt.config.ts
redis.config.ts
database/
migrations/
1234567890-CreateProductsTable.ts
1234567891-CreateCategoriesTable.ts
1234567892-CreateTransactionsTable.ts
seeds/
categories.seed.ts
products.seed.ts
data-source.ts
modules/
products/
dto/
create-product.dto.ts
update-product.dto.ts
get-products.dto.ts
product-response.dto.ts
entities/
product.entity.ts
products.controller.ts
products.service.ts
products.repository.ts
products.module.ts
categories/
dto/
create-category.dto.ts
update-category.dto.ts
category-response.dto.ts
entities/
category.entity.ts
categories.controller.ts
categories.service.ts
categories.repository.ts
categories.module.ts
transactions/
dto/
create-transaction.dto.ts
get-transactions.dto.ts
transaction-response.dto.ts
entities/
transaction.entity.ts
transaction-item.entity.ts
transactions.controller.ts
transactions.service.ts
transactions.repository.ts
transactions.module.ts
auth/
dto/
login.dto.ts
register.dto.ts
strategies/
jwt.strategy.ts
local.strategy.ts
guards/
jwt-auth.guard.ts
local-auth.guard.ts
auth.controller.ts
auth.service.ts
auth.module.ts
users/
dto/
create-user.dto.ts
update-user.dto.ts
entities/
user.entity.ts
users.controller.ts
users.service.ts
users.repository.ts
users.module.ts
sync/
dto/
sync-request.dto.ts
sync-response.dto.ts
sync.controller.ts
sync.service.ts
sync.module.ts
app.module.ts
main.ts
test/
unit/
products/
products.service.spec.ts
products.controller.spec.ts
categories/
transactions/
e2e/
products.e2e-spec.ts
categories.e2e-spec.ts
auth.e2e-spec.ts
.env
.env.example
package.json
tsconfig.json
ormconfig.json
docker-compose.yml
```
---
# Backend Context - Retail POS API
## About This Backend
A comprehensive NestJS REST API backend that powers the Flutter Retail POS mobile application. Provides robust endpoints for product management, category organization, transaction processing, and user authentication, with offline-sync capabilities and real-time data synchronization.
## Target Users
- **Flutter Mobile App**: Primary consumer of the API
- **Admin Dashboard**: Future web-based management interface (optional)
- **Third-party Integrations**: Payment gateways, inventory systems
## Core Features
### 📦 Product Management
**Endpoints**:
- `GET /api/products` - List all products with pagination and filtering
- `GET /api/products/:id` - Get single product details
- `POST /api/products` - Create new product
- `PUT /api/products/:id` - Update product
- `DELETE /api/products/:id` - Delete product
- `GET /api/products/category/:categoryId` - Products by category
- `GET /api/products/search` - Search products
**Features**:
- Full CRUD operations
- Advanced filtering (category, price range, availability)
- Search by name and description
- Stock management
- Image URL storage
- Pagination and sorting
- Soft delete support (optional)
**Business Logic**:
- Validate category exists before creating product
- Check stock availability
- Update product count in category
- Track inventory changes
### 📁 Category Management
**Endpoints**:
- `GET /api/categories` - List all categories
- `GET /api/categories/:id` - Get single category
- `POST /api/categories` - Create new category
- `PUT /api/categories/:id` - Update category
- `DELETE /api/categories/:id` - Delete category
- `GET /api/categories/:id/products` - Products in category
**Features**:
- CRUD operations
- Product count tracking
- Icon/image support
- Color coding
- Cascade delete (optional)
**Business Logic**:
- Prevent deletion if category has products (or cascade)
- Update product count when products added/removed
- Unique category names
### 💰 Transaction Management
**Endpoints**:
- `GET /api/transactions` - List transactions with pagination
- `GET /api/transactions/:id` - Get transaction details
- `POST /api/transactions` - Create new transaction
- `GET /api/transactions/stats` - Transaction statistics
- `GET /api/transactions/daily` - Daily sales report
**Features**:
- Complete transaction logging
- Transaction items tracking
- Subtotal, tax, discount calculation
- Payment method tracking
- Transaction history
- Sales reporting
**Business Logic**:
- Validate stock availability
- Update product stock on transaction
- Calculate totals automatically
- Atomic transaction creation (all or nothing)
- Track product at transaction time (price snapshot)
### 🔐 Authentication & Authorization
**Endpoints**:
- `POST /api/auth/register` - Register new user
- `POST /api/auth/login` - Login user
- `GET /api/auth/profile` - Get current user profile
- `POST /api/auth/refresh` - Refresh access token
**Features**:
- JWT-based authentication
- Password hashing with bcrypt
- Role-based access control (RBAC)
- Token refresh mechanism
- Secure password policies
**Roles**:
- **Admin**: Full access to all endpoints
- **Manager**: Product and category management
- **Cashier**: Transaction processing only
- **User**: Read-only access (optional)
### 🔄 Sync Management
**Endpoints**:
- `POST /api/sync/products` - Sync products to mobile
- `POST /api/sync/categories` - Sync categories to mobile
- `GET /api/sync/status` - Get last sync status
- `GET /api/sync/changes` - Get changes since last sync
**Features**:
- Incremental sync support
- Last modified timestamp tracking
- Change detection
- Bulk data transfer
- Sync conflict resolution
## Technical Stack
### Core Technologies
- **Framework**: NestJS 10.x
- **Language**: TypeScript 5.x
- **Database**: PostgreSQL 15.x
- **ORM**: TypeORM 0.3.x (or Prisma as alternative)
- **Cache**: Redis 7.x
- **Authentication**: JWT (jsonwebtoken)
- **Validation**: class-validator, class-transformer
- **Documentation**: Swagger/OpenAPI
### Key Dependencies
```json
{
"dependencies": {
"@nestjs/common": "^10.0.0",
"@nestjs/core": "^10.0.0",
"@nestjs/platform-express": "^10.0.0",
"@nestjs/typeorm": "^10.0.0",
"@nestjs/jwt": "^10.0.0",
"@nestjs/passport": "^10.0.0",
"@nestjs/swagger": "^7.0.0",
"@nestjs/config": "^3.0.0",
"@nestjs/cache-manager": "^2.0.0",
"@nestjs/throttler": "^5.0.0",
"typeorm": "^0.3.17",
"pg": "^8.11.0",
"bcrypt": "^5.1.0",
"passport-jwt": "^4.0.1",
"class-validator": "^0.14.0",
"class-transformer": "^0.5.1",
"cache-manager": "^5.2.0",
"cache-manager-redis-store": "^3.0.0"
}
}
```
## Database Schema
### Products Table
```sql
CREATE TABLE products (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
name VARCHAR(255) NOT NULL,
description TEXT,
price DECIMAL(10, 2) NOT NULL,
image_url VARCHAR(500),
category_id UUID REFERENCES categories(id) ON DELETE CASCADE,
stock_quantity INTEGER DEFAULT 0,
is_available BOOLEAN DEFAULT true,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
INDEX idx_products_name (name),
INDEX idx_products_category (category_id),
INDEX idx_products_name_category (name, category_id)
);
```
### Categories Table
```sql
CREATE TABLE categories (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
name VARCHAR(255) UNIQUE NOT NULL,
description TEXT,
icon_path VARCHAR(255),
color VARCHAR(50),
product_count INTEGER DEFAULT 0,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
INDEX idx_categories_name (name)
);
```
### Transactions Table
```sql
CREATE TABLE transactions (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
subtotal DECIMAL(10, 2) NOT NULL,
tax DECIMAL(10, 2) DEFAULT 0,
discount DECIMAL(10, 2) DEFAULT 0,
total DECIMAL(10, 2) NOT NULL,
payment_method VARCHAR(50) NOT NULL,
completed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
INDEX idx_transactions_date (completed_at)
);
```
### Transaction Items Table
```sql
CREATE TABLE transaction_items (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
transaction_id UUID REFERENCES transactions(id) ON DELETE CASCADE,
product_id UUID REFERENCES products(id),
product_name VARCHAR(255) NOT NULL,
price DECIMAL(10, 2) NOT NULL,
quantity INTEGER NOT NULL,
line_total DECIMAL(10, 2) NOT NULL,
INDEX idx_transaction_items_transaction (transaction_id),
INDEX idx_transaction_items_product (product_id)
);
```
### Users Table
```sql
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
password VARCHAR(255) NOT NULL,
roles TEXT[] DEFAULT ARRAY['user'],
is_active BOOLEAN DEFAULT true,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
INDEX idx_users_email (email)
);
```
## API Response Format
### Success Response
```json
{
"success": true,
"data": {
// Response data
},
"message": "Operation successful"
}
```
### Paginated Response
```json
{
"success": true,
"data": [
// Array of items
],
"meta": {
"page": 1,
"limit": 20,
"total": 100,
"totalPages": 5
}
}
```
### Error Response
```json
{
"success": false,
"error": {
"statusCode": 400,
"message": "Validation failed",
"details": [
"name must be a string",
"price must be a positive number"
]
},
"timestamp": "2025-01-15T10:30:00.000Z",
"path": "/api/products"
}
```
## Key API Endpoints
### Products API
#### List Products
```http
GET /api/products?page=1&limit=20&categoryId=uuid&search=laptop&minPrice=100&maxPrice=1000
```
**Response**:
```json
{
"success": true,
"data": [
{
"id": "uuid",
"name": "Laptop",
"description": "Gaming laptop",
"price": 999.99,
"imageUrl": "https://...",
"categoryId": "uuid",
"stockQuantity": 50,
"isAvailable": true,
"category": {
"id": "uuid",
"name": "Electronics"
},
"createdAt": "2025-01-15T10:00:00.000Z",
"updatedAt": "2025-01-15T10:00:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 100,
"totalPages": 5
}
}
```
#### Create Product
```http
POST /api/products
Content-Type: application/json
Authorization: Bearer <token>
{
"name": "Laptop",
"description": "Gaming laptop",
"price": 999.99,
"imageUrl": "https://...",
"categoryId": "uuid",
"stockQuantity": 50,
"isAvailable": true
}
```
### Categories API
#### List Categories
```http
GET /api/categories
```
**Response**:
```json
{
"success": true,
"data": [
{
"id": "uuid",
"name": "Electronics",
"description": "Electronic devices",
"iconPath": "/icons/electronics.png",
"color": "#FF5722",
"productCount": 150,
"createdAt": "2025-01-15T10:00:00.000Z"
}
]
}
```
### Transactions API
#### Create Transaction
```http
POST /api/transactions
Content-Type: application/json
Authorization: Bearer <token>
{
"items": [
{
"productId": "uuid",
"quantity": 2
}
],
"paymentMethod": "cash",
"discount": 10.00
}
```
**Response**:
```json
{
"success": true,
"data": {
"id": "uuid",
"subtotal": 1999.98,
"tax": 199.99,
"discount": 10.00,
"total": 2189.97,
"paymentMethod": "cash",
"items": [
{
"id": "uuid",
"productId": "uuid",
"productName": "Laptop",
"price": 999.99,
"quantity": 2,
"lineTotal": 1999.98
}
],
"completedAt": "2025-01-15T10:30:00.000Z"
}
}
```
### Authentication API
#### Login
```http
POST /api/auth/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "Password123!"
}
```
**Response**:
```json
{
"success": true,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "uuid",
"email": "user@example.com",
"name": "John Doe",
"roles": ["admin"]
}
}
}
```
## Caching Strategy
### Cache Layers
1. **Product List Cache**: 5 minutes TTL
2. **Single Product Cache**: 10 minutes TTL
3. **Category List Cache**: 15 minutes TTL
4. **Transaction Stats Cache**: 1 hour TTL
### Cache Invalidation
- Invalidate on CREATE, UPDATE, DELETE operations
- Smart invalidation: Only clear related caches
- Use cache tags for grouped invalidation
### Redis Configuration
```typescript
{
host: process.env.REDIS_HOST,
port: 6379,
ttl: 300, // Default 5 minutes
max: 1000 // Max items in cache
}
```
## Performance Optimization
### Database Optimization
- Index frequently queried columns
- Use query builders for complex queries
- Implement connection pooling (max: 20, min: 5)
- Paginate all list endpoints
- Eager load only necessary relations
### API Optimization
- Enable response compression (gzip)
- Implement rate limiting (100 req/min per IP)
- Cache frequently accessed data
- Use streaming for large responses
- Implement query result caching
### Monitoring
- Log all API requests with response times
- Track database query performance
- Monitor cache hit/miss rates
- Alert on slow endpoints (>1s)
- Track error rates
## Security Implementation
### Authentication
- JWT with 1-day expiration
- Refresh tokens with 7-day expiration
- bcrypt password hashing (10 rounds)
- Rate limiting on auth endpoints (5 req/min)
### Authorization
- Role-based access control (RBAC)
- Protected routes with guards
- Public endpoints clearly marked
- Admin-only endpoints separated
### API Security
- CORS enabled with whitelist
- Helmet for security headers
- Input validation on all endpoints
- SQL injection prevention (TypeORM)
- XSS prevention
- HTTPS only in production
### Environment Variables
```bash
# Application
NODE_ENV=development
PORT=3000
API_PREFIX=api
# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=retail_pos
# JWT
JWT_SECRET=your-super-secret-key-change-in-production
JWT_EXPIRES_IN=1d
# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
CACHE_TTL=300
# CORS
CORS_ORIGIN=http://localhost:3000,capacitor://localhost
# Rate Limiting
THROTTLE_TTL=60
THROTTLE_LIMIT=100
```
## Testing Strategy
### Unit Tests
- Test all service methods
- Test business logic
- Test error handling
- Mock all dependencies
- Aim for 80%+ coverage
### Integration Tests
- Test database operations
- Test repository methods
- Test data transformations
### E2E Tests
- Test complete API flows
- Test authentication flows
- Test CRUD operations
- Test error scenarios
- Test edge cases
### Test Structure
```typescript
describe('ProductsService', () => {
let service: ProductsService;
let repository: MockType<ProductsRepository>;
beforeEach(async () => {
const module = await Test.createTestingModule({
providers: [
ProductsService,
{
provide: ProductsRepository,
useFactory: mockRepository,
},
],
}).compile();
service = module.get(ProductsService);
repository = module.get(ProductsRepository);
});
it('should create a product', async () => {
const dto = { name: 'Test', price: 10 };
repository.create.mockResolvedValue(dto);
const result = await service.create(dto);
expect(result).toEqual(dto);
expect(repository.create).toHaveBeenCalledWith(dto);
});
});
```
## Deployment
### Docker Setup
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/main"]
```
### Docker Compose
```yaml
version: '3.8'
services:
api:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
depends_on:
- postgres
- redis
postgres:
image: postgres:15-alpine
environment:
POSTGRES_DB: retail_pos
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
volumes:
- postgres-data:/var/lib/postgresql/data
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
postgres-data:
```
## Development Workflow
### Setup
```bash
# Install dependencies
npm install
# Setup database
npm run migration:run
npm run seed:run
# Start development server
npm run start:dev
```
### Development Commands
```bash
# Run tests
npm run test
npm run test:e2e
npm run test:cov
# Generate migration
npm run migration:generate -- -n MigrationName
# Run migration
npm run migration:run
# Revert migration
npm run migration:revert
# Seed database
npm run seed:run
```
### API Documentation
- **Swagger UI**: http://localhost:3000/api/docs
- **JSON**: http://localhost:3000/api/docs-json
---
## Remember: ALWAYS DELEGATE TO SPECIALISTS FOR BETTER RESULTS!
When working on this NestJS backend:
- **API/Endpoints** → nestjs-api-expert
- **Database/Entities** → nestjs-database-expert
- **Architecture** → nestjs-architecture-expert
- **Auth/Security** → nestjs-auth-expert
- **Performance** → nestjs-performance-expert
**Think delegation first, implementation second!**