CIDT.CleanArchitecture.Template 1.0.6

🚀 Clean Architecture CIDT - Guía de Usuario

Plantilla profesional de Clean Architecture para ASP.NET Core 8.0 con autenticación completa, CQRS, y mejores prácticas.

---

📦 Instalación

dotnet new install CIDT.CleanArchitecture.Template

---

🎯 Crear un Nuevo Proyecto

Opción 1: Proyecto Básico

dotnet new clean-architecture-cidt -n MiProyecto
cd MiProyecto

Opción 2: Con Configuración Personalizada

dotnet new clean-architecture-cidt -n MiProyecto \
  --DefaultConnection "Server=localhost;Database=MiDb;User Id=sa;Password=MyPass123!;TrustServerCertificate=True" \
  --JwtKey "MiClaveSecretaSuperSeguraDe32CaracteresOMas!" \
  --ApiKeyBrevo "xkeysib-tu-api-key-de-brevo"

---

⚙️ Configuración Inicial

1. Configurar Variables de Entorno

# Copiar archivo de ejemplo
cp .env.example .env

# Editar .env con tus valores
# - Cadena de conexión a base de datos
# - JWT Key (mínimo 32 caracteres)
# - API Key de Brevo (para emails)

2. Aplicar Migraciones de Base de Datos

dotnet ef database update --project src/Infrastructure --startup-project src/Web

Esto crea automáticamente:

• Tablas de usuarios
• Sistema de roles y permisos
• Autenticación JWT
• Auditoría
• Y más...

3. Ejecutar la Aplicación

dotnet run --project src/Web

Accede a:

• Swagger UI: https://localhost:5001/swagger
• Health Check: https://localhost:5001/health

---

🏗️ Estructura del Proyecto

MiProyecto/
├── src/
│   ├── Domain/              # Entidades, lógica de negocio
│   ├── Application/         # Casos de uso, CQRS, DTOs
│   ├── Infrastructure/      # Persistencia, servicios externos
│   └── Web/                # API, endpoints, configuración
├── tests/
│   ├── Application.UnitTests/
│   ├── Application.FunctionalTests/
│   ├── Domain.UnitTests/
│   └── Infrastructure.IntegrationTests/
└── docs/                   # Documentación

---

🔐 Sistema de Autenticación Incluido

La plantilla incluye un sistema completo de autenticación:

Endpoints Disponibles

• POST /api/auth/register - Registrar usuario
• POST /api/auth/login - Iniciar sesión (JWT)
• POST /api/auth/refresh-token - Refrescar token
• POST /api/auth/enable-2fa - Habilitar 2FA
• POST /api/auth/verify-2fa - Verificar código 2FA
• GET /api/users/me - Obtener perfil

Roles Predefinidos

• Administrator: Acceso completo
• Manager: Gestión de usuarios
• User: Usuario estándar

---

💻 Desarrollo

Crear un Nuevo Caso de Uso (CQRS)

Comando (Create, Update, Delete)

dotnet new ca-usecase \
  --name CrearProducto \
  --feature-name Productos \
  --usecase-type command \
  --return-type int

Query (Read)

dotnet new ca-usecase \
  --name ObtenerProductos \
  --feature-name Productos \
  --usecase-type query \
  --return-type "List<ProductoDto>"

Agregar una Nueva Migración

dotnet ef migrations add "NombreMigracion" \
  --project src/Infrastructure \
  --startup-project src/Web \
  --output-dir Data/Migrations

Ejecutar Tests

# Todos los tests
dotnet test

# Con cobertura
dotnet test /p:CollectCoverage=true

---

🗄️ Base de Datos

Motores Soportados

Por defecto usa SQL Server, pero puedes cambiar a:

PostgreSQL

dotnet add src/Infrastructure package Npgsql.EntityFrameworkCore.PostgreSQL
# Actualizar DependencyInjection.cs: UseSqlServer → UseNpgsql

MySQL

dotnet add src/Infrastructure package Pomelo.EntityFrameworkCore.MySql
# Actualizar DependencyInjection.cs: UseSqlServer → UseMySql

SQLite (desarrollo)

dotnet add src/Infrastructure package Microsoft.EntityFrameworkCore.Sqlite
# Actualizar DependencyInjection.cs: UseSqlServer → UseSqlite

Generar Script SQL

dotnet ef migrations script \
  --project src/Infrastructure \
  --startup-project src/Web \
  --output schema.sql

---

📧 Configurar Servicio de Email (Brevo)

1. Crea cuenta en Brevo
2. Obtén tu API Key
3. Configura en .env:

API_KEY_BREVO=xkeysib-tu-api-key
BREVO_SENDER_EMAIL=noreply@tudominio.com
BREVO_SENDER_NAME=TuApp

---

🚀 Despliegue

Publicar para Producción

dotnet publish src/Web -c Release -o ./publish

Configurar para Producción

1. Crear appsettings.Production.json
2. Configurar cadena de conexión de producción
3. Configurar JWT Key segura
4. Aplicar migraciones en servidor

Opciones de Hosting

• Azure App Service
• AWS Elastic Beanstalk
• Docker/Kubernetes
• IIS
• Linux con Nginx

---

🔧 Características Incluidas

✅ Clean Architecture - Separación de responsabilidades
✅ CQRS con MediatR - Comandos y queries separados
✅ Entity Framework Core 8 - ORM moderno
✅ JWT Authentication - Autenticación segura
✅ Two-Factor Authentication (2FA) - Seguridad adicional
✅ Role-Based Access Control (RBAC) - Permisos granulares
✅ FluentValidation - Validación robusta
✅ AutoMapper - Mapeo DTO/Entidad
✅ Swagger/OpenAPI - Documentación automática
✅ Health Checks - Monitoreo de salud
✅ Audit Logs - Registro de acciones
✅ Unit & Integration Tests - Testing completo

---

📚 Documentación Adicional

Dentro del proyecto generado encontrarás:

• README.md - Documentación general
• docs/AUTHENTICATION_SYSTEM.md - Sistema de autenticación
• docs/RBAC_IMPLEMENTATION.md - Control de acceso
• .env.example - Variables de entorno

---

🆘 Solución de Problemas

Error: "Database connection failed"

Verifica tu cadena de conexión en appsettings.json o .env

Error: "JWT validation failed"

Asegúrate de que JWT__KEY tenga al menos 32 caracteres

Error: "Migration failed"

# Eliminar base de datos y recrear
dotnet ef database drop --project src/Infrastructure --startup-project src/Web
dotnet ef database update --project src/Infrastructure --startup-project src/Web

Error: "Port already in use"

Cambia el puerto en src/Web/Properties/launchSettings.json

---

🔄 Actualizar la Plantilla

# Ver versión instalada
dotnet new list

# Actualizar a la última versión
dotnet new update

---

📞 Soporte y Recursos

• Paquete NuGet: https://www.nuget.org/packages/CIDT.CleanArchitecture.Template
• Documentación .NET: https://learn.microsoft.com/en-us/dotnet/
• Clean Architecture: https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
• CQRS Pattern: https://martinfowler.com/bliki/CQRS.html

---

🎓 Ejemplos de Uso

Ejemplo 1: API de E-commerce

dotnet new clean-architecture-cidt -n MiTienda.API
cd MiTienda.API

# Agregar entidades de productos, órdenes, etc.
# Crear casos de uso para carrito de compras
# Implementar pagos con Stripe

Ejemplo 2: Sistema de Gestión

dotnet new clean-architecture-cidt -n GestionEmpresa.API
cd GestionEmpresa.API

# Agregar módulos de empleados, proyectos, tareas
# Implementar reportes y dashboards
# Integrar con servicios externos

Ejemplo 3: API de Microservicios

# Crear múltiples servicios
dotnet new clean-architecture-cidt -n Usuarios.API
dotnet new clean-architecture-cidt -n Productos.API
dotnet new clean-architecture-cidt -n Ordenes.API

# Cada uno con su propia base de datos
# Comunicación via HTTP/gRPC

---

🌟 Mejores Prácticas

1. Usa .env para secretos - Nunca commits archivos con credenciales
2. Escribe tests - Mantén alta cobertura de código
3. Documenta tu API - Usa comentarios XML para Swagger
4. Versionado semántico - Para tu API (v1, v2, etc.)
5. Logging estructurado - Usa Serilog o similar
6. Monitoreo - Implementa Application Insights o similar

---

¡Feliz desarrollo con Clean Architecture! 🎉