284 lines
9.5 KiB
Markdown
284 lines
9.5 KiB
Markdown
# Small Business Inventory Management System
|
|
|
|
A FastAPI-based REST API for managing inventory in small businesses. This system helps small businesses track inventory, manage stock levels, categorize products, and generate reports.
|
|
|
|
## Features
|
|
|
|
- **User Authentication and Authorization**
|
|
- JWT-based authentication
|
|
- Role-based permissions (admin/regular users)
|
|
- Secure password hashing
|
|
|
|
- **Inventory Management**
|
|
- Add, update, and delete inventory items
|
|
- Track stock levels and set reorder points
|
|
- Assign items to categories
|
|
- Track item history with SKU
|
|
|
|
- **Category Management**
|
|
- Organize items into categories
|
|
- Nested categorization support
|
|
- Category-based reporting
|
|
|
|
- **Transaction Tracking**
|
|
- Record purchases, sales, returns, and adjustments
|
|
- Automatic stock level updates
|
|
- Transaction history for audit purposes
|
|
|
|
- **Reporting**
|
|
- Inventory value reports
|
|
- Category summary reports
|
|
- Low stock alerts
|
|
- Transaction summary reports
|
|
|
|
- **API Features**
|
|
- RESTful endpoints following best practices
|
|
- Comprehensive documentation with Swagger UI
|
|
- Health check endpoint for monitoring
|
|
|
|
## Tech Stack
|
|
|
|
- **FastAPI**: Modern, fast web framework for building APIs
|
|
- **SQLAlchemy**: SQL toolkit and ORM
|
|
- **Alembic**: Database migration tool
|
|
- **SQLite**: Simple, file-based database
|
|
- **Pydantic**: Data validation and settings management
|
|
- **Uvicorn**: ASGI server for FastAPI
|
|
- **Python-Jose**: JWT token handling
|
|
- **Passlib**: Password hashing
|
|
- **Ruff**: Python linter for code quality
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── app/
|
|
│ ├── api/
|
|
│ │ ├── deps.py # Dependency injection
|
|
│ │ └── v1/
|
|
│ │ ├── api.py # API router
|
|
│ │ └── endpoints/
|
|
│ │ ├── auth.py # Authentication endpoints
|
|
│ │ ├── categories.py # Category endpoints
|
|
│ │ ├── health.py # Health check endpoint
|
|
│ │ ├── items.py # Inventory item endpoints
|
|
│ │ ├── reports.py # Reporting endpoints
|
|
│ │ ├── transactions.py # Transaction endpoints
|
|
│ │ └── users.py # User endpoints
|
|
│ ├── core/
|
|
│ │ ├── config.py # Application configuration
|
|
│ │ └── security.py # Security utilities
|
|
│ ├── crud/
|
|
│ │ ├── base.py # Base CRUD operations
|
|
│ │ ├── category.py # Category CRUD
|
|
│ │ ├── item.py # Item CRUD
|
|
│ │ ├── transaction.py # Transaction CRUD
|
|
│ │ └── user.py # User CRUD
|
|
│ ├── db/
|
|
│ │ ├── init_db.py # Database initialization
|
|
│ │ ├── session.py # Database session
|
|
│ │ └── utils.py # Database utilities
|
|
│ ├── models/ # SQLAlchemy models
|
|
│ │ ├── base.py # Base model
|
|
│ │ ├── category.py # Category model
|
|
│ │ ├── item.py # Item model
|
|
│ │ ├── transaction.py # Transaction model
|
|
│ │ └── user.py # User model
|
|
│ ├── schemas/ # Pydantic schemas
|
|
│ │ ├── category.py # Category schemas
|
|
│ │ ├── item.py # Item schemas
|
|
│ │ ├── report.py # Report schemas
|
|
│ │ ├── token.py # Token schemas
|
|
│ │ ├── transaction.py # Transaction schemas
|
|
│ │ └── user.py # User schemas
|
|
│ └── storage/ # Storage directory
|
|
│ └── db/ # Database storage
|
|
├── migrations/ # Alembic migrations
|
|
│ ├── env.py # Alembic environment
|
|
│ ├── script.py.mako # Migration script template
|
|
│ └── versions/ # Migration versions
|
|
│ └── initial_migration.py # Initial database schema
|
|
├── alembic.ini # Alembic configuration
|
|
├── main.py # Application entry point
|
|
├── pyproject.toml # Project configuration
|
|
└── requirements.txt # Dependencies
|
|
```
|
|
|
|
## Authentication Flow
|
|
|
|
The system implements a complete authentication flow with the following features:
|
|
|
|
### User Registration and Email Verification
|
|
|
|
1. Users register via `POST /api/v1/auth/register` with their email, password, and optional details
|
|
2. The system creates a new user account with a verification token
|
|
3. If email sending is enabled, a verification email is sent to the user's email address
|
|
4. Users verify their email by clicking the link in the email, which calls `POST /api/v1/auth/verify-email`
|
|
5. Email verification is optional by default but can be enforced by uncommenting the verification check in the login endpoint
|
|
|
|
### Login and Authentication
|
|
|
|
1. Users login via `POST /api/v1/auth/login` with their email (as username) and password
|
|
2. Upon successful authentication, the system returns a JWT access token
|
|
3. This token must be included in the Authorization header as `Bearer {token}` for protected endpoints
|
|
4. Tokens expire after the time specified in `ACCESS_TOKEN_EXPIRE_MINUTES` (default: 8 days)
|
|
|
|
### Password Reset Flow
|
|
|
|
1. Users request a password reset via `POST /api/v1/auth/password-reset-request` with their email
|
|
2. If the email exists, a reset token is generated and a reset link is sent to the user's email
|
|
3. Users reset their password via `POST /api/v1/auth/reset-password` with the token and new password
|
|
4. Reset tokens expire after the time specified in `PASSWORD_RESET_TOKEN_EXPIRE_HOURS` (default: 24 hours)
|
|
|
|
### Environment Variables for Authentication
|
|
|
|
The following environment variables can be configured:
|
|
|
|
```
|
|
# Security
|
|
SECRET_KEY="your-secret-key-here"
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=11520 # 8 days
|
|
|
|
# Email verification
|
|
EMAILS_ENABLED=True
|
|
VERIFICATION_TOKEN_EXPIRE_HOURS=48
|
|
PASSWORD_RESET_TOKEN_EXPIRE_HOURS=24
|
|
|
|
# SMTP settings for email
|
|
SMTP_TLS=True
|
|
SMTP_PORT=587
|
|
SMTP_HOST=smtp.example.com
|
|
SMTP_USER=user@example.com
|
|
SMTP_PASSWORD=your-smtp-password
|
|
EMAILS_FROM_EMAIL=noreply@example.com
|
|
EMAILS_FROM_NAME=YourAppName
|
|
|
|
# First Superuser
|
|
FIRST_SUPERUSER_EMAIL=admin@example.com
|
|
FIRST_SUPERUSER_PASSWORD=adminpassword
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.8 or higher
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository
|
|
2. Install dependencies:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. Initialize the database:
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
4. (Optional) Create a `.env` file in the root directory to customize environment variables:
|
|
|
|
```
|
|
PROJECT_NAME="My Inventory System"
|
|
SECRET_KEY="your-secret-key-here"
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=1440 # 24 hours
|
|
```
|
|
|
|
5. Run the application:
|
|
|
|
```bash
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
6. Open http://localhost:8000/docs to access the Swagger UI documentation
|
|
|
|
## API Documentation
|
|
|
|
- **OpenAPI Documentation**: `/docs`
|
|
- Interactive API documentation with Swagger UI
|
|
- Test endpoints directly from the browser
|
|
|
|
- **Alternative Documentation**: `/redoc`
|
|
- Alternative documentation interface
|
|
|
|
- **OpenAPI JSON**: `/openapi.json`
|
|
- Raw OpenAPI specification
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
- `POST /api/v1/auth/register` - Register a new user
|
|
- `POST /api/v1/auth/login` - Obtain JWT token
|
|
- `POST /api/v1/auth/verify-email` - Verify user's email address
|
|
- `POST /api/v1/auth/password-reset-request` - Request password reset
|
|
- `POST /api/v1/auth/reset-password` - Reset password with token
|
|
- `POST /api/v1/auth/test-token` - Test token validity
|
|
|
|
### Users
|
|
|
|
- `GET /api/v1/users/` - List users (admin only)
|
|
- `POST /api/v1/users/` - Create user (admin only)
|
|
- `GET /api/v1/users/me` - Get current user
|
|
- `PUT /api/v1/users/me` - Update current user
|
|
- `GET /api/v1/users/{user_id}` - Get user by ID
|
|
- `PUT /api/v1/users/{user_id}` - Update user (admin only)
|
|
|
|
### Categories
|
|
|
|
- `GET /api/v1/categories/` - List categories
|
|
- `POST /api/v1/categories/` - Create category (admin only)
|
|
- `GET /api/v1/categories/{id}` - Get category by ID
|
|
- `PUT /api/v1/categories/{id}` - Update category (admin only)
|
|
- `DELETE /api/v1/categories/{id}` - Delete category (admin only)
|
|
|
|
### Inventory Items
|
|
|
|
- `GET /api/v1/items/` - List items (with filtering options)
|
|
- `POST /api/v1/items/` - Create item
|
|
- `GET /api/v1/items/{id}` - Get item by ID
|
|
- `PUT /api/v1/items/{id}` - Update item
|
|
- `DELETE /api/v1/items/{id}` - Delete item
|
|
- `GET /api/v1/items/by-sku/{sku}` - Get item by SKU
|
|
- `GET /api/v1/items/low-stock/` - Get low stock items
|
|
|
|
### Transactions
|
|
|
|
- `GET /api/v1/transactions/` - List transactions (with filtering options)
|
|
- `POST /api/v1/transactions/` - Create transaction
|
|
- `GET /api/v1/transactions/{id}` - Get transaction by ID
|
|
|
|
### Reports
|
|
|
|
- `GET /api/v1/reports/inventory-value` - Inventory value report
|
|
- `GET /api/v1/reports/category-summary` - Category summary report
|
|
- `GET /api/v1/reports/low-stock` - Low stock report
|
|
- `GET /api/v1/reports/transaction-summary` - Transaction summary report
|
|
|
|
### Health Check
|
|
|
|
- `GET /health` - System health check
|
|
- `GET /api/v1/health` - Detailed health check with DB status
|
|
|
|
## Development
|
|
|
|
### Linting
|
|
|
|
The project uses Ruff for linting:
|
|
|
|
```bash
|
|
ruff check .
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. |