# Backend de Gestión Agrícola (DRF)

Backend base para un sistema de gestión agrícola (catálogos, usuarios/roles y generación de boletas origen) implementado con **Django Rest Framework**.

## Stack

- Python 3.10+
- Django 4.2+
- Django Rest Framework 3.14+
- PostgreSQL
- JWT: `djangorestframework-simplejwt`
- Filtros: `django-filter`

## Instalación

### 1) Crear entorno virtual

```bash
python -m venv .venv
```

Activar:

- Windows (PowerShell)

```powershell
.\.venv\Scripts\Activate.ps1
```

### 2) Instalar dependencias

```bash
pip install -r requirements.txt
```

### 3) Variables de entorno

Copia `.env.example` a `.env` y ajusta valores.

Variables principales:

- `DJANGO_SETTINGS_MODULE` (por defecto recomendado: `core.settings.development`)
- `DJANGO_SECRET_KEY`
- `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`

Nota: usa un `DJANGO_SECRET_KEY` de al menos 32 caracteres para evitar advertencias y mejorar seguridad.

### 4) Base de datos

Asegúrate de tener **PostgreSQL** en ejecución y de haber creado la base de datos/usuario según tus variables `DB_*`.

### 5) Migraciones

```bash
python manage.py makemigrations
python manage.py migrate
```

### 6) Crear superusuario

```bash
python manage.py createsuperuser
```

### 7) Bootstrap de roles/permisos

Crea grupos base y asigna permisos:

```bash
python manage.py bootstrap_roles
```

## Ejecución

```bash
python manage.py runserver
```

## Autenticación (JWT)

- `POST /api/v1/auth/token/`
- `POST /api/v1/auth/token/refresh/`

Ejemplo:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin12345"}'
```

Usa el `access` en el header:

```bash
-H "Authorization: Bearer <ACCESS_TOKEN>"
```

## Endpoints principales

### Usuarios

- `GET /api/v1/usuarios/me/` (perfil actual)
- `PATCH /api/v1/usuarios/me/`
- `GET /api/v1/usuarios/users/` (solo admin)
- `POST /api/v1/usuarios/users/` (solo admin)
- `POST /api/v1/usuarios/users/{id}/set-roles/` (solo admin)
- `GET /api/v1/usuarios/groups/` (solo admin)

### Catálogos

Base: `/api/v1/catalogos/`

- `zafras/`
- `variedades/`
- `productores/`
- `contratos/`
- `bodegas/`
- `basculas/`
- `parametros/`
- `castigos/`

Regla de permisos:

- Lectura: usuarios autenticados.
- Escritura: admin o permiso `catalogos.edit`.

### Boletas

Base: `/api/v1/boletas/`

- `GET /api/v1/boletas/` (listar)
- `GET /api/v1/boletas/{id}/` (detalle)
- `POST /api/v1/boletas/generar/` (batch)

Ejemplo batch:

```bash
curl -X POST http://127.0.0.1:8000/api/v1/boletas/generar/ \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "zafra_id": 1,
    "productor_ids": [1],
    "cantidad_boletas_por_productor": 3,
    "generar_qr": true,
    "enviar_email": false,
    "imprimir_pdf": false
  }'
```

Notas:

- Los folios se generan **secuencialmente por zafra** usando `select_for_update` sobre `FolioSecuencia`.
- El QR está implementado como **texto** (`qr_texto`) para dejar lista la estructura.
- Envío de email / PDF están como tareas **simuladas** (logs).

## Auditoría

Modelos críticos incluyen:

- `created_at`, `updated_at`
- `created_by`, `updated_by`

En la API, los `ViewSets` aplican estos campos automáticamente mediante un mixin.

## Pruebas

Incluye un smoke test para generación de boletas.

```bash
$env:DJANGO_SETTINGS_MODULE="core.settings.test"; python manage.py test
```

Si usas CMD en lugar de PowerShell:

```bat
set DJANGO_SETTINGS_MODULE=core.settings.test
python manage.py test
```

## Estructura

- `apps/catalogos`: catálogos
- `apps/usuarios`: usuarios/roles/permisos
- `apps/boletas`: boletas y generación batch
- `utils/audit.py`: mixins de auditoría
- `core/settings`: settings por entorno