first commit
This commit is contained in:
345
README.md
Normal file
345
README.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# EFC V2 Backend API
|
||||
|
||||
Sistema backend para la gestión de **Expedientes Electrónicos de Comercio Exterior** construido con **Django REST Framework**. Este sistema permite la administración completa de pedimentos aduanales, documentos digitales, organizaciones y usuarios en el ámbito del comercio exterior mexicano.
|
||||
|
||||
## 🚀 Características Principales
|
||||
|
||||
- **🔐 Autenticación JWT**: Sistema seguro de autenticación con tokens JWT
|
||||
- **📋 Gestión de Pedimentos**: CRUD completo para pedimentos aduanales
|
||||
- **📁 Gestión de Documentos**: Subida, descarga y administración de documentos
|
||||
- **🏢 Multi-organización**: Soporte para múltiples organizaciones con aislamiento de datos
|
||||
- **👥 Gestión de Usuarios**: Sistema de usuarios con roles y permisos
|
||||
- **📊 Logging y Auditoría**: Sistema completo de logs y monitoreo
|
||||
- **🔄 Integración VUCEM**: Conexión con sistemas externos
|
||||
- **📑 Documentación API**: Swagger/OpenAPI automática
|
||||
- **🔍 Filtros Avanzados**: Búsqueda, filtrado y paginación
|
||||
|
||||
## 🛠️ Tecnologías
|
||||
|
||||
- **Framework**: Django 5.2.3 + Django REST Framework 3.16.0
|
||||
- **Base de Datos**: PostgreSQL (con psycopg2-binary)
|
||||
- **Autenticación**: JWT (djangorestframework-simplejwt)
|
||||
- **Documentación**: drf-yasg (Swagger/OpenAPI)
|
||||
- **Filtros**: django-filter
|
||||
- **CORS**: django-cors-headers
|
||||
- **Archivos**: Pillow para manejo de imágenes
|
||||
|
||||
## 📁 Estructura del Proyecto
|
||||
|
||||
```
|
||||
backend/
|
||||
├── api/ # Aplicaciones de la API
|
||||
│ ├── customs/ # Gestión de aduanas y pedimentos
|
||||
│ ├── record/ # Gestión de documentos
|
||||
│ ├── organization/ # Gestión de organizaciones
|
||||
│ ├── cuser/ # Gestión de usuarios personalizados
|
||||
│ ├── licence/ # Gestión de licencias
|
||||
│ ├── datastage/ # Etapas de datos
|
||||
│ ├── vucem/ # Integración VUCEM
|
||||
│ ├── logger/ # Sistema de logging
|
||||
│ └── notificaciones/ # Sistema de notificaciones
|
||||
├── config/ # Configuración de Django
|
||||
│ ├── settings.py # Configuración principal
|
||||
│ ├── urls.py # URLs principales
|
||||
│ └── wsgi.py # WSGI configuration
|
||||
├── core/ # Utilidades y permisos centrales
|
||||
├── media/ # Archivos subidos
|
||||
├── static/ # Archivos estáticos
|
||||
├── logs/ # Archivos de log
|
||||
├── requirements.txt # Dependencias
|
||||
├── manage.py # Django management script
|
||||
└── Dockerfile # Docker configuration
|
||||
```
|
||||
|
||||
## ⚙️ Instalación y Configuración
|
||||
|
||||
### Requisitos Previos
|
||||
|
||||
- Python 3.11+
|
||||
- PostgreSQL
|
||||
- Git
|
||||
|
||||
### 1. Clonar el Repositorio
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd EFC_V2/backend
|
||||
```
|
||||
|
||||
### 2. Crear Entorno Virtual
|
||||
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Linux/Mac
|
||||
# o
|
||||
venv\Scripts\activate # Windows
|
||||
```
|
||||
|
||||
### 3. Instalar Dependencias
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 4. Configurar Base de Datos
|
||||
|
||||
Crear una base de datos PostgreSQL y configurar las variables de entorno o editar `config/settings.py`:
|
||||
|
||||
```python
|
||||
DATABASES = {
|
||||
'default': {
|
||||
'ENGINE': 'django.db.backends.postgresql',
|
||||
'NAME': 'efc_db',
|
||||
'USER': 'tu_usuario',
|
||||
'PASSWORD': 'tu_contraseña',
|
||||
'HOST': 'localhost',
|
||||
'PORT': '5432',
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Ejecutar Migraciones
|
||||
|
||||
```bash
|
||||
python manage.py makemigrations
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
### 6. Crear Superusuario
|
||||
|
||||
```bash
|
||||
python manage.py createsuperuser
|
||||
```
|
||||
|
||||
### 7. Ejecutar Servidor de Desarrollo
|
||||
|
||||
```bash
|
||||
python manage.py runserver 0.0.0.0:8000
|
||||
```
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
### Ejecutar con Docker
|
||||
|
||||
```bash
|
||||
# Construir imagen
|
||||
docker build -t efc-backend .
|
||||
|
||||
# Ejecutar contenedor
|
||||
docker run -p 8000:8000 efc-backend
|
||||
```
|
||||
|
||||
## 📚 API Endpoints
|
||||
|
||||
### Autenticación
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| POST | `/api/v1/token/` | Obtener token JWT |
|
||||
| POST | `/api/v1/token/refresh/` | Renovar token JWT |
|
||||
|
||||
### Pedimentos
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/customs/pedimentos/` | Listar pedimentos |
|
||||
| POST | `/api/v1/customs/pedimentos/` | Crear pedimento |
|
||||
| GET | `/api/v1/customs/pedimentos/{id}/` | Obtener pedimento |
|
||||
| PUT | `/api/v1/customs/pedimentos/{id}/` | Actualizar pedimento |
|
||||
| DELETE | `/api/v1/customs/pedimentos/{id}/` | Eliminar pedimento |
|
||||
|
||||
### Documentos
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/record/documents/` | Listar documentos |
|
||||
| POST | `/api/v1/record/documents/` | Subir documento |
|
||||
| GET | `/api/v1/record/documents/{id}/` | Obtener documento |
|
||||
| GET | `/api/v1/record/documents/descargar/{id}/` | Descargar documento |
|
||||
| POST | `/api/v1/record/documents/bulk-download/` | Descarga masiva ZIP |
|
||||
|
||||
### Organizaciones
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/organization/organizaciones/` | Listar organizaciones |
|
||||
| POST | `/api/v1/organization/organizaciones/` | Crear organización |
|
||||
|
||||
### Usuarios
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/user/users/` | Listar usuarios |
|
||||
| GET | `/api/v1/user/users/me/` | Perfil del usuario actual |
|
||||
| POST | `/api/v1/user/users/` | Crear usuario |
|
||||
|
||||
### Catálogos
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/customs/aduanas/` | Catálogo de aduanas |
|
||||
| GET | `/api/v1/customs/agentesaduanales/` | Agentes aduanales |
|
||||
| GET | `/api/v1/customs/tiposoperacion/` | Tipos de operación |
|
||||
| GET | `/api/v1/customs/regimenes/` | Regímenes aduanales |
|
||||
|
||||
## 🔐 Autenticación
|
||||
|
||||
El sistema utiliza **JWT (JSON Web Tokens)** para autenticación:
|
||||
|
||||
### 1. Obtener Token
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/token/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "tu_usuario", "password": "tu_contraseña"}'
|
||||
```
|
||||
|
||||
### 2. Usar Token
|
||||
|
||||
```bash
|
||||
curl -X GET http://localhost:8000/api/v1/customs/pedimentos/ \
|
||||
-H "Authorization: Bearer tu_token_jwt"
|
||||
```
|
||||
|
||||
## 🔍 Filtros y Búsqueda
|
||||
|
||||
La API soporta filtros avanzados en la mayoría de endpoints:
|
||||
|
||||
### Ejemplos de Filtros
|
||||
|
||||
```bash
|
||||
# Filtrar pedimentos por patente
|
||||
GET /api/v1/customs/pedimentos/?patente=1234
|
||||
|
||||
# Búsqueda por texto
|
||||
GET /api/v1/customs/pedimentos/?search=contribuyente
|
||||
|
||||
# Ordenamiento
|
||||
GET /api/v1/customs/pedimentos/?ordering=-created_at
|
||||
|
||||
# Paginación
|
||||
GET /api/v1/customs/pedimentos/?page=2&page_size=10
|
||||
```
|
||||
|
||||
## 📊 Sistema de Logging
|
||||
|
||||
El sistema incluye un completo sistema de logging y auditoría:
|
||||
|
||||
### Tipos de Logs
|
||||
|
||||
- **Request Logs**: Todas las peticiones HTTP
|
||||
- **User Activity**: Actividades de usuarios
|
||||
- **Error Logs**: Errores del sistema
|
||||
|
||||
### Endpoints de Logging
|
||||
|
||||
```bash
|
||||
# Ver estadísticas de requests
|
||||
GET /api/v1/logger/requests/statistics/
|
||||
|
||||
# Ver logs de actividad
|
||||
GET /api/v1/logger/activities/
|
||||
|
||||
# Ver logs de errores
|
||||
GET /api/v1/logger/errors/
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
```bash
|
||||
# Ejecutar tests
|
||||
python manage.py test
|
||||
|
||||
# Ejecutar tests con coverage
|
||||
pip install coverage
|
||||
coverage run --source='.' manage.py test
|
||||
coverage report
|
||||
```
|
||||
|
||||
## 📖 Documentación API
|
||||
|
||||
### Swagger UI
|
||||
Accede a la documentación interactiva:
|
||||
- **Swagger**: http://localhost:8000/api/v1/swagger/
|
||||
- **ReDoc**: http://localhost:8000/api/v1/redoc/
|
||||
|
||||
### Características de la Documentación
|
||||
|
||||
- ✅ Autenticación JWT integrada
|
||||
- ✅ Ejemplos de requests/responses
|
||||
- ✅ Pruebas en tiempo real
|
||||
- ✅ Esquemas de datos detallados
|
||||
|
||||
## 🔧 Configuración de Producción
|
||||
|
||||
### Variables de Entorno
|
||||
|
||||
```bash
|
||||
export DEBUG=False
|
||||
export SECRET_KEY=tu_clave_secreta_segura
|
||||
export ALLOWED_HOSTS=tu-dominio.com,127.0.0.1
|
||||
export DATABASE_URL=postgresql://user:pass@localhost/db
|
||||
```
|
||||
|
||||
### Configuraciones de Seguridad
|
||||
|
||||
- Configurar `ALLOWED_HOSTS` apropiadamente
|
||||
- Usar `DEBUG=False`
|
||||
- Configurar HTTPS
|
||||
- Configurar CORS apropiadamente
|
||||
- Usar base de datos segura
|
||||
|
||||
## 🚀 Despliegue
|
||||
|
||||
### Con Docker Compose
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
web:
|
||||
build: .
|
||||
ports:
|
||||
- "8000:8000"
|
||||
environment:
|
||||
- DEBUG=False
|
||||
depends_on:
|
||||
- db
|
||||
|
||||
db:
|
||||
image: postgres:13
|
||||
environment:
|
||||
POSTGRES_DB: efc_db
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: password
|
||||
```
|
||||
|
||||
## 🤝 Contribución
|
||||
|
||||
1. Fork el proyecto
|
||||
2. Crear una rama feature (`git checkout -b feature/AmazingFeature`)
|
||||
3. Commit los cambios (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Push a la rama (`git push origin feature/AmazingFeature`)
|
||||
5. Abrir un Pull Request
|
||||
|
||||
## 📄 Licencia
|
||||
|
||||
Este proyecto está bajo la Licencia MIT. Ver el archivo `LICENSE` para más detalles.
|
||||
|
||||
## 🆘 Soporte
|
||||
|
||||
Para soporte técnico contactar a: support@aduanasoft.com.mx
|
||||
|
||||
## 📝 Changelog
|
||||
|
||||
### v2.0.0
|
||||
- ✅ Migración completa a Django REST Framework
|
||||
- ✅ Sistema de autenticación JWT
|
||||
- ✅ API RESTful completa
|
||||
- ✅ Sistema de logging avanzado
|
||||
- ✅ Documentación automática
|
||||
- ✅ Soporte multi-organización
|
||||
|
||||
---
|
||||
|
||||
**Desarrollado con ❤️ para el comercio exterior mexicano**
|
||||
# EFC_backend
|
||||
Reference in New Issue
Block a user