api-inventario/SPEC.md

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