Add SPEC.md

2026-04-11 03:57:50 +00:00
commit 8bd2e2aa40
1 changed files with 168 additions and 0 deletions
--- a/SPEC.md
+++ b/SPEC.md
@@ -0,0 +1,168 @@
+# 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_