linkbay-wms 0.1.0
A lightweight, reusable Warehouse Management System library for the LinkBay CMS ecosystem
License: MIT
Requires Python: >=3.8
Keywords: warehouse, wms, inventory, linkbay, cms, ecommerce, stock-management

# LinkBay-WMS v0.1.0

[![License](https://img.shields.io/badge/license-MIT-blue)]() [![Python](https://img.shields.io/badge/python-3.8+-blue)]()

A lightweight, reusable Warehouse Management System library for the LinkBay CMS ecosystem.

## Overview

LinkBay-WMS provides warehouse operations and inventory management functionality that integrates seamlessly with other LinkBay packages like `linkbay-auth`, `linkbay-multitenant`, `linkbay-catalog`, and `linkbay-orders`.

### Key Features

- **Lightweight**: No heavy dependencies, minimal complexity
- **Reusable**: Dynamic, not tied to specific database schemas
- **Composable**: Works with any SQLAlchemy models provided by the user
- **Integration-Ready**: Designed to work with the LinkBay ecosystem

### Core Principle

This library does **NOT** include models or database connections. Instead, it provides:

- Service classes that accept models as parameters
- Business logic functions
- FastAPI router factories
- Utility functions

**You bring your own models and database sessions.**

## Prima di iniziare

LinkBay-WMS è ideale se:
- Hai bisogno di gestione magazzino e inventario
- Vuoi integrare con LinkBay CMS (catalog, orders, multitenant)
- Preferisci una soluzione leggera e flessibile
- Vuoi usare i tuoi modelli database

Non è adatto se:
- Cerchi un WMS standalone con UI completa
- Hai bisogno di funzionalità avanzate come barcode scanning (implementale tu)

## Installazione

```bash
pip install linkbay-wms
```

Oppure l'ultima versione dal repository:

```bash
pip install git+https://github.com/AlessioQuagliara/LinkBay-WMS
```

## Come funziona (3 passi)

### 1. Definisci i tuoi modelli

```python
from sqlalchemy import Column, Integer, String, Float, DateTime, ForeignKey, Boolean, JSON
from sqlalchemy.ext.declarative import declarative_base
from datetime import datetime

Base = declarative_base()

class Warehouse(Base):
    __tablename__ = "warehouses"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    code = Column(String)
    is_active = Column(Boolean, default=True)
    max_capacity = Column(Integer, nullable=True)

class Inventory(Base):
    __tablename__ = "inventory"
    id = Column(Integer, primary_key=True)
    product_id = Column(Integer, ForeignKey("products.id"))
    warehouse_id = Column(Integer, ForeignKey("warehouses.id"))
    quantity = Column(Integer, default=0)
    reserved_quantity = Column(Integer, default=0)
    unit_price = Column(Float, nullable=True)

class StockMovement(Base):
    __tablename__ = "stock_movements"
    id = Column(Integer, primary_key=True)
    product_id = Column(Integer)
    warehouse_id = Column(Integer, nullable=True)
    movement_type = Column(String)
    quantity = Column(Integer)
    reference_number = Column(String)
    from_location = Column(String, nullable=True)
    to_location = Column(String, nullable=True)
    metadata = Column(JSON, default={})
    created_at = Column(DateTime, default=datetime.utcnow)
```

### 2. Crea il router FastAPI

```python
from fastapi import FastAPI
from linkbay_wms import create_wms_router
from myapp.models import Warehouse, Inventory, StockMovement
from myapp.database import get_db

app = FastAPI()

wms_router = create_wms_router(
    warehouse_model=Warehouse,
    inventory_model=Inventory,
    movement_model=StockMovement,
    get_db=get_db,
    prefix="/api/v1/wms",
    tags=["Warehouse Management"]
)

app.include_router(wms_router)
```

### 3. Usa l'API

```bash
# Ricevi stock
curl -X POST "http://localhost:8000/api/v1/wms/inventory/receive" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "warehouse_id": 1,
    "quantity": 100,
    "reference_number": "PO-2024-001"
  }'

# Controlla disponibilità
curl "http://localhost:8000/api/v1/wms/inventory/available/123?warehouse_id=1"

# Trasferisci tra magazzini
curl -X POST "http://localhost:8000/api/v1/wms/movements/transfer" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "from_warehouse_id": 1,
    "to_warehouse_id": 2,
    "quantity": 50
  }'
```

## Esempio avanzato: Uso diretto dei servizi

Puoi usare i servizi direttamente senza FastAPI:

```python
from linkbay_wms.services import InventoryService, MovementService
from linkbay_wms.types import AdjustmentReason
from myapp.models import Inventory, StockMovement
from myapp.database import SessionLocal

# Inizializza servizi
inventory_service = InventoryService(Inventory, StockMovement)
movement_service = MovementService(StockMovement, Inventory)

db = SessionLocal()

# Ricevi stock
result = inventory_service.receive_stock(
    db=db,
    product_id=123,
    warehouse_id=1,
    quantity=100,
    reference_number="PO-2024-001"
)

# Aggiustamento inventario
adjustment = inventory_service.adjust_inventory(
    db=db,
    product_id=123,
    warehouse_id=1,
    quantity_delta=-5,
    reason=AdjustmentReason.DAMAGE,
    notes="Danneggiato in magazzino"
)

# Trasferimento
transfer = movement_service.transfer_stock(
    db=db,
    product_id=123,
    from_warehouse_id=1,
    to_warehouse_id=2,
    quantity=50
)

db.close()
```

## Caratteristiche principali

### 1. Operazioni Magazzino
- Gestione magazzini multipli
- Tracking capacità
- Ottimizzazione allocazione stock
- Report stock basso

### 2. Gestione Inventario
- Ricezione stock
- Aggiustamenti (danni, perdite, conteggi)
- Prenotazioni per ordini
- Query disponibilità

### 3. Movimenti Stock
- Tracking completo movimenti
- Trasferimenti tra magazzini
- Cronologia e report
- Audit trail

### 4. Picking e Fulfillment
- Allocazione automatica stock
- Task di picking
- Imballaggio e spedizione
- Integrazione con ordini

### 5. Multi-Tenant
Integrazione con `linkbay-multitenant`:

```python
from linkbay_multitenant import get_current_tenant

wms_router = create_wms_router(
    warehouse_model=Warehouse,
    inventory_model=Inventory,
    movement_model=StockMovement,
    get_db=get_db,
    get_current_tenant=get_current_tenant
)
```

## API Endpoints

Quando usi `create_wms_router()`:

### Magazzini
- `GET /wms/warehouses` - Lista magazzini
- `GET /wms/warehouses/{id}` - Dettagli magazzino
- `GET /wms/warehouses/{id}/capacity` - Capacità

### Inventario
- `GET /wms/inventory` - Lista inventario
- `GET /wms/inventory/available/{product_id}` - Stock disponibile
- `GET /wms/inventory/low-stock` - Articoli sotto scorta
- `GET /wms/inventory/valuation` - Valore inventario
- `POST /wms/inventory/receive` - Ricevi stock
- `POST /wms/inventory/adjust` - Aggiusta inventario

### Movimenti
- `GET /wms/movements` - Lista movimenti
- `GET /wms/movements/summary/{product_id}` - Sommario movimenti
- `POST /wms/movements/transfer` - Trasferisci stock

### Picking
- `POST /wms/picking/allocate` - Alloca stock
- `POST /wms/picking/pick` - Pick ordine
- `POST /wms/picking/ship` - Marca spedito

## Integrazione Ecosistema LinkBay

### Con linkbay-catalog
```python
from linkbay_catalog import Product
from linkbay_wms import InventoryService

inventory_service.receive_stock(
    db, product_id=product.id, warehouse_id=1, quantity=100
)
```

### Con linkbay-orders
```python
from linkbay_orders import Order
from linkbay_wms import PickingService

picking_service.allocate_stock_for_order(
    db, order_items=order.items, warehouse_id=1
)
```

## Utility Functions

```python
from linkbay_wms.utils import (
    calculate_inventory_value,
    is_low_stock,
    calculate_stock_coverage,
    generate_reference_number
)

value = calculate_inventory_value(quantity=100, unit_price=29.99)
low = is_low_stock(available=5, threshold=10)
days = calculate_stock_coverage(available_quantity=100, daily_demand=5)
ref = generate_reference_number("RCV")
```

## Testing

```bash
# Installa dipendenze test
pip install pytest pytest-asyncio httpx

# Run tests
pytest
```

## Limitazioni note

- Non include UI/frontend
- Non include barcode scanning (implementalo tu se necessario)
- Non gestisce automazione fisica (robot, conveyor)
- Focus su business logic, non hardware integration


## Roadmap consigliata


## Licenza

MIT. Puoi usarla e modificarla liberamente, assicurandoti di valutarne i rischi nel tuo contesto.

## Supporto

- Issues: https://github.com/AlessioQuagliara/LinkBay-WMS/issues
- Email: quagliara.alessio@gmail.com

Contribuisci, apri una issue o raccontaci come stai usando la libreria 🧡