# API Inventario - Specification

## 1. Project Overview

- **Project**: API Inventario
- **Type**: Microservicio REST
- **Description**: Microservicio para gestionar inventario (productos, categorías, stock, movimientos)
- **Tech Stack**: Python FastAPI, PostgreSQL, SQLAlchemy ORM, Docker
- **Repository**: https://gitea.danielarroyo.cl/proyectos/api-inventario

---

## 2. Domain Model

### 2.1 Entities

#### Category (Categoría)
| Field | Type | Description |
|-------|------|-------------|
| id | UUID | Primary key |
| name | str(100) | Nombre único |
| description | str(500) | Descripción opcional |
| created_at | datetime | Timestamp creación |

#### Product (Producto)
| Field | Type | Description |
|-------|------|-------------|
| id | UUID | Primary key |
| sku | str(50) | SKU único |
| name | str(200) | Nombre |
| description | str(1000) | Descripción |
| category_id | UUID | FK → Category |
| price | Decimal(10,2) | Precio unitario |
| min_stock | int | Stock mínimo (alerta) |
| current_stock | int | Stock actual |
| created_at | datetime | Timestamp creación |
| updated_at | datetime | Timestamp actualización |

#### StockMovement (Movimiento de Stock)
| Field | Type | Description |
|-------|------|-------------|
| id | UUID | Primary key |
| product_id | UUID | FK → Product |
| type | enum | IN (entrada), OUT (salida), ADJUST (ajuste) |
| quantity | int | Cantidad (positiva) |
| reason | str(200) | Motivo del movimiento |
| created_at | datetime | Timestamp |

---

## 3. API Endpoints

### 3.1 Categories
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/categories` | Crear categoría |
| GET | `/api/v1/categories` | Listar categorías |
| GET | `/api/v1/categories/{id}` | Obtener categoría |
| PUT | `/api/v1/categories/{id}` | Actualizar categoría |
| DELETE | `/api/v1/categories/{id}` | Eliminar categoría |

### 3.2 Products
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/products` | Crear producto |
| GET | `/api/v1/products` | Listar productos (paginated) |
| GET | `/api/v1/products/{id}` | Obtener producto |
| PUT | `/api/v1/products/{id}` | Actualizar producto |
| DELETE | `/api/v1/products/{id}` | Eliminar producto |
| GET | `/api/v1/products/low-stock` | Productos con stock bajo |

### 3.3 Stock Movements
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/stock/move` | Registrar movimiento |
| GET | `/api/v1/stock/history/{product_id}` | Historial de movimientos |
| GET | `/api/v1/stock/summary` | Resumen de stock global |

### 3.4 Health
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |

---

## 4. Acceptance Criteria

1. ✅ CRUD completo de categorías
2. ✅ CRUD completo de productos
3. ✅ Registro de movimientos de stock (IN/OUT/ADJUST)
4. ✅ Validación: no permitir salidas que dejen stock negativo
5. ✅ Alerta de stock bajo cuando `current_stock < min_stock`
6. ✅ Paginación en listado de productos
7. ✅ API documentada con OpenAPI/Swagger
8. ✅ Tests unitarios para core logic
9. ✅ Docker ready (Dockerfile + docker-compose)

---

## 5. Project Structure

```
api-inventario/
├── SPEC.md
├── README.md
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app
│   ├── config.py            # Settings
│   ├── database.py          # SQLAlchemy setup
│   ├── models/
│   │   ├── __init__.py
│   │   ├── category.py
│   │   ├── product.py
│   │   └── stock_movement.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── category.py
│   │   ├── product.py
│   │   └── stock_movement.py
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── categories.py
│   │   ├── products.py
│   │   └── stock.py
│   └── services/
│       ├── __init__.py
│       ├── category_service.py
│       ├── product_service.py
│       └── stock_service.py
└── tests/
    ├── __init__.py
    ├── conftest.py
    ├── test_categories.py
    ├── test_products.py
    └── test_stock.py
```

---

## 6. TODO Tasks

| Task | Title | Priority | Labels |
|------|-------|----------|--------|
| TASK-001 | Estructura inicial del proyecto | high | backend,python |
| TASK-002 | Configurar base de datos y modelos SQLAlchemy | high | backend,python |
| TASK-003 | Implementar CRUD Categories | medium | backend,python |
| TASK-004 | Implementar CRUD Products | medium | backend,python |
| TASK-005 | Implementar gestión de Stock Movements | medium | backend,python |
| TASK-006 | Documentación OpenAPI y README | low | spec |
| TASK-007 | Docker setup (Dockerfile + docker-compose) | medium | devops |
| TASK-008 | Tests unitarios | medium | test |

---

## 7. Configuration

Environment variables:
- `DATABASE_URL` (default: postgresql://user:pass@localhost:5432/inventario)
- `API_VERSION` (default: v1)
- `DEBUG` (default: false)

---

_v1.0.0 - 2026-04-11_