# Tourism Management System — Generated Backend

## Overview

This is a **FastAPI-based backend** for a comprehensive Tourism Management System. It manages tour packages, bookings, customer relationships, service providers, payments, reviews, cancellations, and financial operations across the tourism industry.

The system supports **7 user roles**:
- **Super Admin** — full system access and configuration
- **Tour Manager** — manages tour packages, schedules, and resources
- **Booking Agent** — creates and manages customer bookings
- **Tour Guide** — conducts tours and submits expenses
- **Service Provider** — manages hotels, transportation, and other services
- **Customer** — searches, books, and reviews tours
- **Finance Manager** — handles payments, commissions, and expenses

The backend includes **10 core modules**:
1. **User Management** — authentication, authorization, and role-specific profiles
2. **Tour Catalog** — packages, destinations, itineraries, and seasonal pricing
3. **Booking Management** — customer bookings, travelers, and tour schedules
4. **Service Provider Management** — hotels, room types, and transportation
5. **Payment Management** — payment processing, invoicing, and discounts
6. **Review Management** — customer reviews and ratings
7. **Cancellation Management** — cancellation requests and refund workflows
8. **Financial Management** — expenses and agent commissions
9. **Notification Management** — multi-channel alerts and messages
10. **Document Management** — document uploads and storage

## Requirements

- **Python 3.11+**
- **uv** (fast Python package installer)
- **FastAPI** and **Uvicorn** (installed via dependencies)

## Install uv

Install `uv` using the official installer:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

After installation, restart your terminal or run:

```bash
source $HOME/.cargo/env
```

## Install Dependencies

All dependencies are managed in `pyproject.toml`. Install them with:

```bash
uv sync
```

This will create a virtual environment and install:
- FastAPI
- Uvicorn
- Pydantic
- Python-Jose (JWT)
- Passlib (password hashing)
- Python-multipart (file uploads)

## Run the Backend

Start the development server with auto-reload:

```bash
uv run uvicorn main:app --reload
```

The API will be available at:
- **Base URL**: `http://localhost:8000`
- **Interactive Docs**: `http://localhost:8000/docs`
- **ReDoc**: `http://localhost:8000/redoc`

## API Docs

The backend provides **auto-generated interactive API documentation** via Swagger UI at `/docs`.

### Key Endpoints

#### Authentication
- `POST /auth/register` — Register new user
- `POST /auth/login` — Login and receive JWT token
- `POST /auth/logout` — Logout user
- `POST /auth/reset-password` — Reset password

#### Tour Packages
- `GET /tour-packages` — List all tour packages
- `POST /tour-packages` — Create new tour package
- `GET /tour-packages/{id}` — Get tour package by ID
- `GET /tour-packages/{id}/details` — Get detailed package with itineraries, destinations, and amenities
- `GET /tour-packages/search` — Search packages by filters
- `GET /tour-packages/{id}/availability` — Check availability for dates

#### Bookings
- `GET /bookings` — List all bookings
- `POST /bookings` — Create new booking
- `GET /bookings/{id}` — Get booking by ID
- `GET /bookings/{id}/details` — Get detailed booking with customer, travelers, payments, and invoice
- `POST /bookings/{id}/confirm` — Confirm booking
- `POST /bookings/{id}/cancel` — Cancel booking
- `POST /bookings/{id}/modify` — Modify booking details

#### Payments
- `GET /payments` — List all payments
- `POST /payments` — Create payment
- `POST /payments/process` — Process payment transaction
- `POST /payments/{id}/refund` — Refund payment

#### Reviews
- `GET /reviews` — List all reviews
- `POST /reviews` — Create review
- `GET /reviews/{id}/details` — Get detailed review with customer and tour info
- `POST /reviews/{id}/publish` — Publish review
- `POST /reviews/{id}/respond` — Add management response

#### Tour Schedules
- `GET /tour-schedules` — List all tour schedules
- `POST /tour-schedules` — Create tour schedule
- `GET /tour-schedules/{id}/details` — Get detailed schedule with resources
- `POST /tour-schedules/{id}/assign-guide` — Assign tour guide
- `POST /tour-schedules/{id}/assign-resources` — Assign hotels and transportation
- `POST /tour-schedules/{id}/complete` — Mark tour as completed

#### Cancellations
- `GET /cancellation-requests` — List cancellation requests
- `POST /cancellation-requests` — Create cancellation request
- `POST /cancellation-requests/{id}/approve` — Approve cancellation
- `POST /cancellation-requests/{id}/reject` — Reject cancellation

#### Financial
- `GET /expenses` — List expenses
- `POST /expenses` — Submit expense
- `POST /expenses/{id}/approve` — Approve expense
- `POST /expenses/{id}/reject` — Reject expense
- `GET /commissions` — List commissions
- `POST /commissions/{id}/approve` — Approve commission
- `POST /commissions/{id}/pay` — Mark commission as paid

#### Reports
- `GET /reports/bookings` — Booking reports
- `GET /reports/revenue` — Revenue reports
- `GET /reports/commissions` — Commission reports
- `GET /reports/expenses` — Expense reports

## OpenAPI JSON

The OpenAPI specification is available at:

```
http://localhost:8000/openapi.json
```

You can import this into Postman, Insomnia, or other API clients.

## Project Files

```
tourism-management-system/
├── main.py                 # FastAPI application entry point
├── pyproject.toml          # Project dependencies and metadata
├── README.md               # This file
└── (additional files to be organized):
    ├── routers/            # API route handlers
    ├── services/           # Business logic layer
    ├── models/             # Pydantic models and schemas
    ├── database/           # Database connection and ORM
    └── tests/              # Unit and integration tests
```

## Example Workflow

### 1. Register a New Customer

```bash
curl -X POST "http://localhost:8000/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "password": "SecurePass123!",
    "role": "customer",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  }'
```

### 2. Login and Get JWT Token

```bash
curl -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "password": "SecurePass123!"
  }'
```

Response:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

### 3. Search Tour Packages

```bash
curl -X GET "http://localhost:8000/tour-packages/search?destination=Paris&min_price=500&max_price=2000" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

### 4. Create a Booking

```bash
curl -X POST "http://localhost:8000/bookings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "tour_schedule_id": "schedule-123",
    "number_of_adults": 2,
    "number_of_children": 1,
    "number_of_infants": 0,
    "special_requests": "Vegetarian meals preferred",
    "travelers": [
      {
        "traveler_type": "adult",
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1985-06-15",
        "passport_number": "AB1234567",
        "is_primary": true
      },
      {
        "traveler_type": "adult",
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": "1987-03-22",
        "passport_number": "CD7654321",
        "is_primary": false
      },
      {
        "traveler_type": "child",
        "first_name": "Emily",
        "last_name": "Doe",
        "date_of_birth": "2015-09-10",
        "is_primary": false
      }
    ]
  }'
```

### 5. Get Booking Details

```bash
curl -X GET "http://localhost:8000/bookings/booking-456/details" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

Response includes customer info, tour schedule, travelers, payments, and invoice with line items.

### 6. Process Payment

```bash
curl -X POST "http://localhost:8000/payments/process" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "booking_id": "booking-456",
    "payment_method": "credit_card",
    "amount": 1500.00,
    "currency": "USD"
  }'
```

## Next Steps

This generated backend provides a solid foundation. To make it production-ready, consider:

1. **Database Persistence**
   - Integrate SQLAlchemy or another ORM
   - Connect to PostgreSQL, MySQL, or MongoDB
   - Implement database migrations with Alembic

2. **Authentication & Authorization**
   - Implement JWT token validation middleware
   - Add role-based access control (RBAC) decorators
   - Secure password hashing with bcrypt
   - Add refresh token mechanism

3. **Code Organization**
   - Split `main.py` into separate modules:
     - `routers/` — API endpoints grouped by domain
     - `services/` — Business logic and workflows
     - `models/` — Pydantic schemas and database models
     - `database/` — Database connection and session management
     - `utils/` — Helper functions and utilities

4. **Testing**
   - Write unit tests with pytest
   - Add integration tests for API endpoints
   - Implement test fixtures and factories
   - Set up CI/CD pipeline with automated testing

5. **Additional Features**
   - File upload handling for documents and images
   - Email notification service integration
   - Payment gateway integration (Stripe, PayPal)
   - Background task processing with Celery
   - Caching with Redis
   - Rate limiting and API throttling
   - Logging and monitoring (Sentry, DataDog)
   - API versioning strategy

6. **Business Logic**
   - Implement cancellation fee calculation based on policy
   - Add seasonal pricing multiplier logic
   - Implement loyalty points calculation
   - Add discount validation and application
   - Create automated notification triggers
   - Implement tour capacity management
   - Add commission calculation workflows

7. **Documentation**
   - Add detailed docstrings to all functions
   - Create API usage guides
   - Document business rules and workflows
   - Add deployment instructions

8. **Security**
   - Add input validation and sanitization
   - Implement CORS policies
   - Add request rate limiting
   - Enable HTTPS in production
   - Implement audit logging
   - Add data encryption for sensitive fields

Start by setting up your database connection and implementing authentication, then gradually add business logic and tests for each module.