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