# Invoice Generation Service

This is a FastAPI application for generating and managing invoices. It allows users to register, login, and manage their invoices with full authentication and user-specific data access.

## Features

- User registration and authentication with JWT
- Generate invoices with automatic invoice number generation
- Store invoice details in SQLite database
- Retrieve invoice information by ID or invoice number
- Update invoice details and status
- Delete invoices
- User-specific invoice management (users can only access their own invoices)
- Advanced search and filtering options
- Web-based user interface for invoice management
- Health check endpoint

## Technical Stack

- **Framework**: FastAPI
- **Database**: SQLite with SQLAlchemy ORM
- **Migrations**: Alembic
- **Validation**: Pydantic
- **Authentication**: JWT (JSON Web Tokens)
- **Password Hashing**: Bcrypt
- **Frontend**: Jinja2 Templates, HTML, CSS, JavaScript
- **Linting**: Ruff

## Project Structure

```
.
├── alembic.ini               # Alembic configuration file
├── app                       # Application package
│   ├── api                   # API routes
│   │   └── routes            # API route modules
│   │       ├── __init__.py   # Routes initialization
│   │       ├── invoices.py   # Invoice API routes
│   │       └── frontend.py   # Frontend routes
│   ├── core                  # Core functionality
│   │   ├── config.py         # Application settings
│   │   ├── database.py       # Database connection setup
│   │   └── utils.py          # Utility functions
│   ├── models                # SQLAlchemy models
│   │   ├── __init__.py       # Models initialization
│   │   └── invoice.py        # Invoice and InvoiceItem models
│   ├── schemas               # Pydantic schemas
│   │   ├── __init__.py       # Schemas initialization
│   │   └── invoice.py        # Invoice-related schemas
│   ├── static                # Static files
│   │   ├── css               # CSS styles
│   │   │   └── styles.css    # Main stylesheet
│   │   └── js                # JavaScript files
│   │       └── main.js       # Main JavaScript file
│   └── templates             # Jinja2 templates
│       ├── base.html         # Base template with layout
│       ├── home.html         # Home page
│       ├── create_invoice.html # Invoice creation form
│       ├── search_invoice.html # Search for invoices
│       └── invoice_details.html # Invoice details page
├── main.py                   # Application entry point
├── migrations                # Alembic migrations
│   ├── env.py                # Alembic environment
│   ├── script.py.mako        # Migration script template
│   └── versions              # Migration scripts
│       └── ef0aaab3a275_initial_database_tables.py  # Initial migration
├── requirements.txt          # Project dependencies
└── pyproject.toml            # Ruff configuration
```

## API Endpoints

### Health Check

- `GET /health`: Check if the service is running

### Authentication API

- `POST /api/v1/auth/register`: Register a new user
  - Request body: User registration details (email, username, password, etc.)
  - Returns: User details (without password)
- `POST /api/v1/auth/login`: Login and get an access token
  - Request body: Form data with username/email and password
  - Returns: JWT access token
- `GET /api/v1/auth/me`: Get current user details
  - Headers: `Authorization: Bearer {token}`
  - Returns: Current user details

### Invoice Management API

All invoice endpoints require authentication with a valid JWT token in the Authorization header: `Authorization: Bearer {token}`

- `POST /api/v1/invoices`: Create a new invoice (associated with the authenticated user)
- `GET /api/v1/invoices`: List invoices belonging to the authenticated user (with pagination)
  - Query parameters:
    - `skip`: Number of records to skip (default: 0)
    - `limit`: Maximum number of records to return (default: 100)
    - `fields`: Comma-separated list of fields to include in the response (e.g., "id,invoice_number,total_amount")
    - `status`: Filter invoices by status (e.g., "PENDING", "PAID", "CANCELLED")
    - `sort_order`: Sort by creation date, either "asc" (oldest first) or "desc" (newest first, default)
    - Many more filtering options available (see Advanced Filtering section)
- `GET /api/v1/invoices/{invoice_id}`: Get a specific invoice by ID (must belong to the authenticated user)
  - Query parameters:
    - `fields`: Comma-separated list of fields to include in the response (e.g., "id,invoice_number,total_amount")
- `GET /api/v1/invoices/find`: Find an invoice by invoice number (must belong to the authenticated user)
  - Query parameters:
    - `invoice_number`: Invoice number to search for (required)
    - `fields`: Comma-separated list of fields to include in the response (e.g., "id,invoice_number,total_amount")
- `PATCH /api/v1/invoices/{invoice_id}`: Update an invoice (must belong to the authenticated user)
- `PATCH /api/v1/invoices/{invoice_id}/status`: Update invoice status (must belong to the authenticated user)
- `DELETE /api/v1/invoices/{invoice_id}`: Delete an invoice (must belong to the authenticated user)

### Frontend Routes

- `GET /`: Home page with list of recent invoices
- `GET /create`: Form to create a new invoice
- `POST /create`: Process invoice creation form
- `GET /search`: Form to search for invoices by number
- `POST /search`: Process invoice search
- `GET /invoice/{invoice_id}`: View invoice details
- `POST /invoice/{invoice_id}/status`: Update invoice status

## Setup and Installation

1. Clone the repository
2. Install dependencies:
   ```
   pip install -r requirements.txt
   ```
3. Run migrations:
   ```
   alembic upgrade head
   ```
4. Start the application:
   ```
   uvicorn main:app --reload
   ```

## Authentication

The application uses JWT (JSON Web Tokens) for authentication. Here's how to use it:

### User Registration

To create a new user account:

```
POST /api/v1/auth/register
```

Request body:
```json
{
  "email": "user@example.com",
  "username": "user123",
  "password": "securepassword",
  "full_name": "John Doe"
}
```

### User Login

To log in and get an access token:

```
POST /api/v1/auth/login
```

This endpoint accepts form data (not JSON) with:
- `username`: Your username or email
- `password`: Your password

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

### Using the Token

Include the token in the Authorization header for all invoice-related requests:

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Getting Current User

To get the details of the currently authenticated user:

```
GET /api/v1/auth/me
```

Headers:
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## API Documentation

Once the application is running, you can access:
- Interactive API documentation at `/docs` (Swagger UI)
- Alternative API documentation at `/redoc` (ReDoc)

## Web Interface

The application comes with a full web interface that allows users to:
- View a list of recent invoices on the home page
- Create new invoices using a dynamic form
- Search for existing invoices by invoice number
- View detailed invoice information
- Update invoice status (PENDING, PAID, CANCELLED)
- Print invoices

## Invoice Number Format

Invoices are automatically assigned a unique invoice number with the format:
- `INV-YYYYMM-XXXXXX`, where:
  - `INV` is a fixed prefix
  - `YYYYMM` is the year and month (e.g., 202307 for July 2023)
  - `XXXXXX` is a random alphanumeric string

## Query Parameters

### Field Filtering

The API supports field filtering for GET operations. This allows clients to request only the specific fields they need, which can improve performance and reduce bandwidth usage.

#### How to Use Field Filtering:

1. Add a `fields` query parameter to GET requests
2. Specify a comma-separated list of field names to include in the response

#### Example:

To get only the ID, invoice number, and total amount of invoices:
```
GET /api/v1/invoices?fields=id,invoice_number,total_amount
```

This would return:
```json
[
  {
    "id": 1,
    "invoice_number": "INV-202307-A1B2C3",
    "total_amount": 100.0
  },
  {
    "id": 2,
    "invoice_number": "INV-202307-D4E5F6",
    "total_amount": 200.0
  }
]
```

### Status Filtering

The API supports filtering invoices by their status (PENDING, PAID, CANCELLED).

#### How to Use Status Filtering:

1. Add a `status` query parameter to the GET request
2. Specify one of the allowed status values: "PENDING", "PAID", or "CANCELLED"

#### Example:

To get only paid invoices:
```
GET /api/v1/invoices?status=PAID
```

To combine with other parameters:
```
GET /api/v1/invoices?status=PENDING&fields=id,invoice_number,total_amount&limit=5
```

### Advanced Filtering

The API supports advanced filtering options for more precise control over your invoice queries.

#### Date Range Filtering

Filter invoices by creation date or due date:

- `created_after`: Filter invoices created on or after this date (YYYY-MM-DD)
- `created_before`: Filter invoices created on or before this date (YYYY-MM-DD)
- `due_after`: Filter invoices due on or after this date (YYYY-MM-DD)
- `due_before`: Filter invoices due on or before this date (YYYY-MM-DD)

Examples:

```
# Get invoices created in January 2023
GET /api/v1/invoices?created_after=2023-01-01&created_before=2023-01-31

# Get overdue invoices (due before today)
GET /api/v1/invoices?due_before=2023-07-01&status=PENDING
```

#### Customer Filtering

Search for invoices by customer information:

- `customer_name`: Filter invoices by customer name (case-insensitive, partial match)
- `customer_email`: Filter invoices by customer email (case-insensitive, partial match)

Examples:

```
# Find all invoices for customers with "smith" in their name
GET /api/v1/invoices?customer_name=smith

# Find invoices for customers with a specific email domain
GET /api/v1/invoices?customer_email=example.com
```

#### Amount Range Filtering

Filter invoices by total amount:

- `min_amount`: Filter invoices with total amount greater than or equal to this value
- `max_amount`: Filter invoices with total amount less than or equal to this value

Examples:

```
# Get invoices with amounts between $100 and $500
GET /api/v1/invoices?min_amount=100&max_amount=500

# Get high-value invoices
GET /api/v1/invoices?min_amount=1000
```

### Advanced Sorting

The API supports sorting invoices by various fields:

- `sort_by`: Field to sort by. Available options:
  - `date_created`: Sort by creation date (default)
  - `due_date`: Sort by due date
  - `total_amount`: Sort by invoice amount
  - `customer_name`: Sort alphabetically by customer name
- `sort_order`: Sort direction:
  - `asc`: Ascending order (oldest/smallest/A-Z first)
  - `desc`: Descending order (newest/largest/Z-A first, this is the default)

Examples:

```
# Get highest-value invoices first
GET /api/v1/invoices?sort_by=total_amount&sort_order=desc

# Get invoices sorted alphabetically by customer name
GET /api/v1/invoices?sort_by=customer_name&sort_order=asc

# Get invoices with the earliest due dates first
GET /api/v1/invoices?sort_by=due_date&sort_order=asc
```

### Combining Filters

All filter parameters can be combined for precise results:

```
# Get pending invoices over $500 created in 2023, sorted by amount (highest first)
GET /api/v1/invoices?status=PENDING&min_amount=500&created_after=2023-01-01&sort_by=total_amount&sort_order=desc

# Get paid invoices for a specific customer
GET /api/v1/invoices?status=PAID&customer_name=acme&sort_by=date_created&sort_order=desc
```

### Available Fields:

Invoices have the following fields that can be filtered:
- `id`
- `invoice_number`
- `date_created`
- `due_date`
- `total_amount`
- `status`
- `customer_name`
- `customer_email`
- `customer_address`
- `notes`
- `items` (this includes related invoice items)