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
|
||||
- Docker & Docker Compose
|
||||
## 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 & npm
|
||||
- Node.js 18+
|
||||
- Docker (for PostgreSQL)
|
||||
|
||||
## 1. Start Database
|
||||
Start the PostgreSQL database using Docker Compose:
|
||||
### Backend Setup
|
||||
|
||||
1. Start PostgreSQL:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 2. Run Backend
|
||||
Open a terminal and run the Backend API:
|
||||
2. Run the backend:
|
||||
```bash
|
||||
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)
|
||||
Open a new terminal and run the BFF API:
|
||||
```bash
|
||||
dotnet run --project src/Hospitality.BFF
|
||||
```
|
||||
The BFF will run on `http://localhost:5116`.
|
||||
Swagger UI: `http://localhost:5116/swagger`
|
||||
Backend runs on `http://localhost:5163`
|
||||
|
||||
### Frontend Setup
|
||||
|
||||
## 4. Run Frontend
|
||||
Open a new terminal and start the React Frontend:
|
||||
```bash
|
||||
cd src/hospitality-web
|
||||
npm install # if not already done
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
The Frontend will run on `http://localhost:5173`.
|
||||
|
||||
## Verification
|
||||
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.
|
||||
Frontend runs on `http://localhost:5173`
|
||||
|
||||
## Architecture
|
||||
- **Frontend**: React + Vite + Tailwind CSS. Proxies `/api` requests to BFF.
|
||||
- **BFF**: ASP.NET Core Web API. Proxies requests to Backend.
|
||||
- **Backend**: ASP.NET Core Web API + EF Core + PostgreSQL. Handles domain logic and data persistence.
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user