Update README with complete documentation
This commit is contained in:
steinhelge
@@ -1,50 +1,246 @@
|
|||||||
# Hospitality Project Walkthrough
|
# Digital Access and Serving System
|
||||||
|
|
||||||
This document guides you through running the Hospitality event management 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.
|
||||||
|
|
||||||
## Prerequisites
|
## Features
|
||||||
- Docker & Docker Compose
|
|
||||||
|
### 🔐 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
|
- .NET 9 SDK
|
||||||
- Node.js & npm
|
- Node.js 18+
|
||||||
|
- Docker (for PostgreSQL)
|
||||||
|
|
||||||
## 1. Start Database
|
### Backend Setup
|
||||||
Start the PostgreSQL database using Docker Compose:
|
|
||||||
|
1. Start PostgreSQL:
|
||||||
```bash
|
```bash
|
||||||
docker-compose up -d
|
docker-compose up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
## 2. Run Backend
|
2. Run the backend:
|
||||||
Open a terminal and run the Backend API:
|
|
||||||
```bash
|
```bash
|
||||||
dotnet run --project src/Hospitality.Backend
|
dotnet run --project src/Hospitality.Backend
|
||||||
```
|
```
|
||||||
The Backend will run on `http://localhost:5163` (or similar, check output).
|
|
||||||
Swagger UI: `http://localhost:5163/swagger`
|
|
||||||
|
|
||||||
## 3. Run BFF (Backend for Frontend)
|
Backend runs on `http://localhost:5163`
|
||||||
Open a new terminal and run the BFF API:
|
|
||||||
```bash
|
### Frontend Setup
|
||||||
dotnet run --project src/Hospitality.BFF
|
|
||||||
```
|
|
||||||
The BFF will run on `http://localhost:5116`.
|
|
||||||
Swagger UI: `http://localhost:5116/swagger`
|
|
||||||
|
|
||||||
## 4. Run Frontend
|
|
||||||
Open a new terminal and start the React Frontend:
|
|
||||||
```bash
|
```bash
|
||||||
cd src/hospitality-web
|
cd src/hospitality-web
|
||||||
npm install # if not already done
|
npm install
|
||||||
npm run dev
|
npm run dev
|
||||||
```
|
```
|
||||||
The Frontend will run on `http://localhost:5173`.
|
|
||||||
|
|
||||||
## Verification
|
Frontend runs on `http://localhost:5173`
|
||||||
1. Open `http://localhost:5173` in your browser.
|
|
||||||
2. You should see the "Hospitality Admin" dashboard.
|
|
||||||
3. It will attempt to fetch people from the API. Initially, it will show "No people found."
|
|
||||||
4. You can use the Backend Swagger UI (`http://localhost:5163/swagger`) to POST a new Person, and then refresh the frontend to see it.
|
|
||||||
|
|
||||||
## Architecture
|
## Test Accounts
|
||||||
- **Frontend**: React + Vite + Tailwind CSS. Proxies `/api` requests to BFF.
|
|
||||||
- **BFF**: ASP.NET Core Web API. Proxies requests to Backend.
|
The system is pre-seeded with test accounts:
|
||||||
- **Backend**: ASP.NET Core Web API + EF Core + PostgreSQL. Handles domain logic and data persistence.
|
|
||||||
|
- **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.
|
||||||
|
|||||||
Reference in New Issue
Block a user