steinhelge
247 lines
6.5 KiB
Markdown
247 lines
6.5 KiB
Markdown
# Digital Access and Serving System
|
|
|
|
A complete event management solution for handling VIP areas, serving quotas, and group management using QR codes. Built with .NET 9, React, TypeScript, and PostgreSQL.
|
|
|
|
## Features
|
|
|
|
### 🔐 Authentication & Authorization
|
|
- JWT-based authentication
|
|
- Role-based access control (Admin, Staff, Guest)
|
|
- Protected routes with automatic token management
|
|
- Secure login with test accounts included
|
|
|
|
### 👨💼 Admin Interface
|
|
- Event management (create, list, view details)
|
|
- Group management with contact information
|
|
- Product management (drinks, meals, access, special)
|
|
- Person management with auto-generated QR codes
|
|
- Quota assignment to individuals
|
|
- Full QR code display with copy functionality
|
|
|
|
### 📱 Staff Scanner
|
|
- QR code lookup (manual entry)
|
|
- Person details and quota status display
|
|
- Transaction recording with "Use 1" and "Use 2" buttons
|
|
- Real-time quota updates
|
|
|
|
### 🎫 Guest View
|
|
- **Auto-load personal data on login** - No search required!
|
|
- Large scannable QR code display
|
|
- Quota status with progress bars
|
|
- Real-time remaining amounts
|
|
|
|
## Technology Stack
|
|
|
|
### Backend
|
|
- .NET 9 Web API
|
|
- ASP.NET Core Identity
|
|
- JWT Bearer Authentication
|
|
- Entity Framework Core 9
|
|
- PostgreSQL with Npgsql
|
|
- Swagger/OpenAPI
|
|
|
|
### Frontend
|
|
- React 18 with TypeScript
|
|
- Vite (build tool)
|
|
- React Router 7
|
|
- TanStack Query (React Query)
|
|
- Bootstrap 5 + react-bootstrap
|
|
- Axios with JWT interceptors
|
|
- qrcode.react
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- .NET 9 SDK
|
|
- Node.js 18+
|
|
- Docker (for PostgreSQL)
|
|
|
|
### Backend Setup
|
|
|
|
1. Start PostgreSQL:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
2. Run the backend:
|
|
```bash
|
|
dotnet run --project src/Hospitality.Backend
|
|
```
|
|
|
|
Backend runs on `http://localhost:5163`
|
|
|
|
### Frontend Setup
|
|
|
|
```bash
|
|
cd src/hospitality-web
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Frontend runs on `http://localhost:5173`
|
|
|
|
## Test Accounts
|
|
|
|
The system is pre-seeded with test accounts:
|
|
|
|
- **Admin**: `admin@example.com` / `Admin123!`
|
|
- **Staff**: `staff@example.com` / `Staff123!`
|
|
- **Guest**: `guest@example.com` / `Guest123!`
|
|
|
|
## Quick Start Guide
|
|
|
|
### 1. Login
|
|
1. Navigate to `http://localhost:5173`
|
|
2. You'll be redirected to `/login`
|
|
3. Login with one of the test accounts above
|
|
|
|
### 2. Admin Workflow
|
|
1. View events list
|
|
2. Click "Summer Festival 2025"
|
|
3. See groups and products
|
|
4. Click "VIP Sponsors" group
|
|
5. View people with full QR codes
|
|
6. Click "Copy QR Code" for John Doe
|
|
7. Assign new quotas to people
|
|
|
|
### 3. Staff Workflow
|
|
1. Login as `staff@example.com`
|
|
2. Navigate to "Staff Scanner"
|
|
3. Paste a QR code (copy from admin interface)
|
|
4. Click "Lookup Person"
|
|
5. See quotas and click "Use 1" to record consumption
|
|
|
|
### 4. Guest Workflow
|
|
1. Login as `guest@example.com`
|
|
2. **Your QR code and quotas load automatically!**
|
|
3. Show the QR code to staff for scanning
|
|
4. View your remaining quotas with progress bars
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/auth/login` - Login
|
|
- `POST /api/auth/register` - Register new user (Admin only)
|
|
- `GET /api/auth/me` - Current user info
|
|
- `GET /api/auth/me/person` - Current user's person data (Guest)
|
|
|
|
### Events
|
|
- `GET /api/events` - List all events
|
|
- `GET /api/events/{id}` - Get event details
|
|
- `POST /api/events` - Create event
|
|
- `PUT /api/events/{id}` - Update event
|
|
- `DELETE /api/events/{id}` - Delete event
|
|
|
|
### Groups
|
|
- `GET /api/groups/event/{eventId}` - List groups for event
|
|
- `GET /api/groups/{id}` - Get group details
|
|
- `POST /api/groups` - Create group
|
|
- `PUT /api/groups/{id}` - Update group
|
|
- `DELETE /api/groups/{id}` - Delete group
|
|
- `POST /api/groups/{groupId}/people` - Add person to group
|
|
- `POST /api/groups/{groupId}/people/{personId}/quotas` - Assign quota
|
|
|
|
### Products
|
|
- `GET /api/products/event/{eventId}` - List products for event
|
|
- `POST /api/products` - Create product
|
|
- `PUT /api/products/{id}` - Update product
|
|
- `DELETE /api/products/{id}` - Delete product
|
|
|
|
### QR Code
|
|
- `GET /api/qrcode/{qrCode}` - Lookup person by QR code
|
|
|
|
### Transactions
|
|
- `POST /api/transactions` - Record transaction
|
|
- `GET /api/transactions/person/{personId}` - Get person's transactions
|
|
|
|
## Sample Data
|
|
|
|
The system includes comprehensive test data:
|
|
|
|
### Events
|
|
- **Summer Festival 2025** (July 1-3, Oslo)
|
|
- **Winter Gala 2025** (December 15, Bergen)
|
|
|
|
### Products
|
|
- Beer, Wine, Lunch, Dinner, VIP Lounge Access
|
|
- Champagne, Gala Dinner
|
|
|
|
### Groups & People
|
|
- **VIP Sponsors**: John Doe, Jane Smith, Bob Wilson
|
|
- **Event Staff**: Alice Staff, Charlie Staff
|
|
- **General Admission**: Emily Guest, David Guest
|
|
|
|
## Database Schema
|
|
|
|
### Core Tables
|
|
- **Events**: Event information (name, dates, location)
|
|
- **Products**: Products/services (type: Access, Drink, Meal, Special)
|
|
- **Groups**: Guest groups with contact info
|
|
- **People**: Individual guests with QR codes
|
|
- **PersonQuotas**: Quota assignments (initial/used amounts)
|
|
- **Transactions**: Consumption history
|
|
|
|
### Identity Tables
|
|
- **AspNetUsers**: User accounts (linked to People for guests)
|
|
- **AspNetRoles**: Roles (Admin, Staff, Guest)
|
|
- **AspNetUserRoles**: User-role mappings
|
|
- Plus standard Identity tables for claims, logins, tokens
|
|
|
|
## Security Features
|
|
|
|
- JWT tokens with 8-hour expiration
|
|
- Password requirements (8+ chars, upper, lower, digit, special char)
|
|
- Role-based endpoint protection
|
|
- Automatic token refresh on API calls
|
|
- Auto-logout on 401 responses
|
|
- Protected routes on frontend
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
```bash
|
|
dotnet test
|
|
```
|
|
|
|
### Database Migrations
|
|
```bash
|
|
# Create a new migration
|
|
dotnet ef migrations add MigrationName --project src/Hospitality.Infrastructure --startup-project src/Hospitality.Backend
|
|
|
|
# Apply migrations
|
|
dotnet ef database update --project src/Hospitality.Infrastructure --startup-project src/Hospitality.Backend
|
|
|
|
# Drop database (reset)
|
|
dotnet ef database drop --force --project src/Hospitality.Infrastructure --startup-project src/Hospitality.Backend
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
hospitality/
|
|
├── src/
|
|
│ ├── Hospitality.Domain/ # Core entities and enums
|
|
│ ├── Hospitality.Infrastructure/ # EF Core, DbContext, migrations
|
|
│ ├── Hospitality.Backend/ # ASP.NET Core Web API
|
|
│ └── hospitality-web/ # React frontend
|
|
├── docker-compose.yml # PostgreSQL container
|
|
└── README.md
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
- Camera QR scanner integration
|
|
- CSV import for bulk person creation
|
|
- Email/SMS QR code delivery
|
|
- Transaction history reports
|
|
- Offline support for staff app
|
|
- Real-time updates with SignalR
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Support
|
|
|
|
For issues or questions, please open an issue on GitHub.
|