From 26fe36ca52e96a549facce2345e39cbd4f0eb91b Mon Sep 17 00:00:00 2001 From: Kevin Rosales Date: Mon, 22 Sep 2025 18:42:36 -0600 Subject: [PATCH] first commit --- README.md | 345 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 345 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e8a7eaf --- /dev/null +++ b/README.md @@ -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 +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