98d4bb52c3
- JWT authentication with Supabase integration - Role-based access control (Admin, Owner, Staff, Auditor) - Universal database adapter (Prisma/Supabase/MongoDB support) - User management with hierarchical permissions - Redis caching service (configured but optional) - Comprehensive API documentation - Production-ready NestJS architecture - Migration scripts for provider switching - Swagger/OpenAPI documentation
224 lines
5.1 KiB
Markdown
224 lines
5.1 KiB
Markdown
# Receipt & Ticket Verification API
|
|
|
|
A production-ready backend API for receipt & ticket verification system with OCR processing, role-based access, reporting, and performance monitoring.
|
|
|
|
## Features
|
|
|
|
- 🔐 **Authentication & Authorization**
|
|
- JWT-based authentication
|
|
- Supabase integration for OTP
|
|
- Role-based access control (RBAC)
|
|
- Telegram ID compatibility
|
|
|
|
- 👥 **User Management**
|
|
- System Admin, Business Owner, Staff, Auditor roles
|
|
- Hierarchical user creation
|
|
- Redis-cached role lookups
|
|
|
|
- 🧾 **Receipt Processing** (Coming Soon)
|
|
- OCR with Tesseract.js
|
|
- Asynchronous processing with BullMQ
|
|
- Duplicate detection
|
|
- Fraud flagging
|
|
|
|
- 📊 **Reporting & Analytics** (Coming Soon)
|
|
- Daily sales summaries
|
|
- Transaction reports
|
|
- Performance metrics
|
|
- CSV/PDF exports
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: NestJS (TypeScript)
|
|
- **Database**: PostgreSQL with Prisma ORM
|
|
- **Cache**: Redis
|
|
- **Queue**: BullMQ
|
|
- **Auth**: JWT + Supabase
|
|
- **Storage**: Supabase Storage
|
|
- **OCR**: Tesseract.js
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+
|
|
- PostgreSQL
|
|
- Redis
|
|
- Supabase account
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository
|
|
```bash
|
|
git clone <repository-url>
|
|
cd receipt-verification-api
|
|
```
|
|
|
|
2. Install dependencies
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Set up environment variables
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
```
|
|
|
|
4. Set up the database
|
|
```bash
|
|
npx prisma generate
|
|
npx prisma db push
|
|
```
|
|
|
|
5. Start the development server
|
|
```bash
|
|
npm run start:dev
|
|
```
|
|
|
|
The API will be available at `http://localhost:3000/api/v1`
|
|
|
|
## Environment Variables
|
|
|
|
```env
|
|
# Database
|
|
DATABASE_URL="postgresql://username:password@localhost:5432/receipt_verification?schema=public"
|
|
|
|
# Supabase
|
|
SUPABASE_URL="https://your-project.supabase.co"
|
|
SUPABASE_ANON_KEY="your-anon-key"
|
|
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
|
|
|
|
# JWT
|
|
JWT_SECRET="your-jwt-secret-key"
|
|
JWT_EXPIRES_IN="7d"
|
|
|
|
# Redis
|
|
REDIS_HOST="localhost"
|
|
REDIS_PORT=6379
|
|
REDIS_PASSWORD=""
|
|
|
|
# App
|
|
PORT=3000
|
|
NODE_ENV="development"
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/v1/auth/login` - Login with credentials
|
|
- `POST /api/v1/auth/register` - Register new user (admin/owner only)
|
|
- `POST /api/v1/auth/request-otp` - Request OTP via Supabase
|
|
- `POST /api/v1/auth/verify-otp` - Verify OTP and login
|
|
- `GET /api/v1/auth/profile` - Get current user profile
|
|
- `GET /api/v1/auth/validate` - Validate JWT token
|
|
|
|
### Users
|
|
- `GET /api/v1/users` - List users (filtered by role)
|
|
- `GET /api/v1/users/:id` - Get user by ID
|
|
- `POST /api/v1/users/staff` - Create staff/auditor
|
|
- `PATCH /api/v1/users/:id` - Update user
|
|
- `DELETE /api/v1/users/:id` - Deactivate user
|
|
- `GET /api/v1/users/my-staff` - Get owner's staff
|
|
|
|
## User Roles & Permissions
|
|
|
|
### System Admin
|
|
- Full system access
|
|
- Manage all users
|
|
- View all reports
|
|
- System configuration
|
|
|
|
### Business Owner
|
|
- Create/manage staff and auditors
|
|
- View business reports
|
|
- Manage receipts
|
|
- Verify transactions
|
|
|
|
### Staff (Cashier)
|
|
- Upload receipts
|
|
- View own receipts
|
|
- Basic verification tasks
|
|
|
|
### Auditor
|
|
- Read-only access to reports
|
|
- View receipts for auditing
|
|
- No modification permissions
|
|
|
|
## Database Schema
|
|
|
|
The system uses Prisma with PostgreSQL. Key entities:
|
|
|
|
- **User**: Authentication and role management
|
|
- **Receipt**: Receipt data and OCR results
|
|
- **Verification**: Receipt verification records
|
|
- **PerformanceMetric**: System performance tracking
|
|
|
|
## Development
|
|
|
|
### Scripts
|
|
|
|
```bash
|
|
npm run start:dev # Development server with hot reload
|
|
npm run build # Build for production
|
|
npm run start:prod # Start production server
|
|
npm run lint # Run ESLint
|
|
npm run test # Run tests
|
|
npm run prisma:studio # Open Prisma Studio
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
src/
|
|
├── features/ # Feature modules
|
|
│ ├── auth/ # Authentication & authorization
|
|
│ ├── users/ # User management
|
|
│ ├── receipts/ # Receipt processing (coming soon)
|
|
│ ├── ocr/ # OCR processing (coming soon)
|
|
│ └── reports/ # Reporting (coming soon)
|
|
├── shared/ # Shared utilities
|
|
│ ├── config/ # Configuration
|
|
│ ├── constants/ # Constants and enums
|
|
│ ├── decorators/ # Custom decorators
|
|
│ ├── guards/ # Auth guards
|
|
│ ├── services/ # Shared services
|
|
│ └── utils/ # Utility functions
|
|
└── prisma/ # Database schema
|
|
```
|
|
|
|
## Security Features
|
|
|
|
- JWT token authentication
|
|
- Role-based access control
|
|
- Password hashing with bcrypt
|
|
- Request validation with class-validator
|
|
- CORS protection
|
|
- Rate limiting (recommended for production)
|
|
|
|
## Caching Strategy
|
|
|
|
- User roles cached in Redis (1 hour TTL)
|
|
- User profiles cached (5 minutes TTL)
|
|
- Automatic cache invalidation on updates
|
|
|
|
## Next Steps
|
|
|
|
1. Implement OCR module with BullMQ
|
|
2. Add receipt upload and processing
|
|
3. Create verification workflows
|
|
4. Build reporting system
|
|
5. Add performance monitoring
|
|
6. Implement notification system
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. |