169 lines
5.1 KiB
Markdown
169 lines
5.1 KiB
Markdown
# 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_
|