Tecnología

Este documento resume las tecnologías, versiones y herramientas necesarias para desarrollar y ejecutar IZ-CentralForms en ambiente local. La información de infraestructura de servidor, IIS y producción se documenta en infraestructura.md y despliegue.md.

Resumen tecnológico

Área	Tecnología / configuración	Uso	Estado
Backend	.NET / ASP.NET Core	API REST, controllers, configuración HTTP, Swagger, Health Check, archivos estáticos y Rate Limiting.	Implementado
Aplicación	C# / Services / DTOs	Casos de uso, contratos e interfaces.	Implementado
Dominio	C# Entities	Modelo base del negocio.	Implementado
Persistencia	Entity Framework Core + SQL Server LocalDB	ORM, migraciones y base local.	Implementado local
API Docs	Swagger / OpenAPI	Prueba y documentación interactiva de endpoints.	Implementado local
SDK frontend	JavaScript vanilla	Render dinámico de formularios desde wwwroot/sdk.	Implementado
Email local	SMTP + Mailpit	Pruebas de notificación sin envío real productivo.	Implementado local
Hosting futuro	IIS + .NET Hosting Bundle	Publicación en Windows Server.	Documentado / pendiente

LocalDB

SQL Server LocalDB es solo para desarrollo local. Para IIS, QA, staging o producción se debe usar una instancia real de SQL Server.

Versiones y configuración actual

Elemento	Valor
Target Framework	net10.0
Proyecto API	Microsoft.NET.Sdk.Web
EF Core	10.0.7
EF Core SQL Server	10.0.7
EF Core Tools	10.0.7
EF Core Design	10.0.7
Logging Abstractions	10.0.7
Swagger / OpenAPI	Swashbuckle.AspNetCore 6.6.2
Base local	(localdb)\\MSSQLLocalDB
Base de datos	CentralFormsDb
SMTP local	localhost:1025, SSL deshabilitado
Ambiente local	ASPNETCORE_ENVIRONMENT=Development
URL HTTP	http://localhost:5273
URL HTTPS	https://localhost:7122

Actualización de versiones

Si cambia el TargetFramework, los paquetes NuGet o launchSettings.json, esta sección debe actualizarse junto con los .csproj y la configuración local.

Proyectos de la solución

CentralForms.Api
CentralForms.Application
CentralForms.Domain
CentralForms.Infrastructure

Proyecto	Tipo	Responsabilidad
CentralForms.Api	ASP.NET Core Web API	Endpoints, Swagger, configuración HTTP, Health Check, Rate Limiting y SDK estático.
CentralForms.Application	Class Library	DTOs, interfaces y servicios de aplicación.
CentralForms.Domain	Class Library	Entidades del dominio.
CentralForms.Infrastructure	Class Library	EF Core, SQL Server, SMTP, webhooks y servicios externos.

Herramientas locales

Herramienta	Uso
.NET SDK	Compilar y ejecutar la solución.
EF Core CLI	Crear y aplicar migraciones.
SQL Server LocalDB / Developer	Base de datos local.
SSMS / Azure Data Studio	Consulta y administración de base de datos.
Mailpit	Captura local de correos en localhost:1025.
Navegador	Swagger y pruebas del SDK.
PowerShell	Scripts y comandos de soporte.

Comandos principales

dotnet restore
dotnet build .\CentralForms.Api\CentralForms.Api.csproj
dotnet run --project .\CentralForms.Api\CentralForms.Api.csproj
dotnet clean

Validar entorno local:

dotnet --info
dotnet --list-sdks
dotnet --list-runtimes
dotnet list .\CentralForms.Api\CentralForms.Api.csproj package
dotnet list .\CentralForms.Infrastructure\CentralForms.Infrastructure.csproj package

Entity Framework Core

Crear migración:

dotnet ef migrations add NombreMigracion --project .\CentralForms.Infrastructure\CentralForms.Infrastructure.csproj --startup-project .\CentralForms.Api\CentralForms.Api.csproj --context CentralFormsDbContext

Aplicar migraciones:

dotnet ef database update --project .\CentralForms.Infrastructure\CentralForms.Infrastructure.csproj --startup-project .\CentralForms.Api\CentralForms.Api.csproj --context CentralFormsDbContext

SDK Embed JS

El SDK permite integrar formularios dinámicos en páginas externas sin construir el formulario manualmente.

Elemento	Ruta / valor
Archivo SDK	CentralForms.Api/wwwroot/sdk/centralforms.js
URL local SDK	https://localhost:7122/sdk/centralforms.js
Ejemplo local	https://localhost:7122/examples/contacto.html

Capacidades principales:

• Render dinámico del formulario.
• Validación visual en frontend.
• Bloqueo de doble submit.
• Manejo de estados loading, ready, submitting, success y error.
• Renovación de CSRF después de envío exitoso.
• Callbacks de ciclo de vida.
• Auto-init mediante atributos data-*.

Validación backend

El SDK mejora la experiencia de usuario, pero no reemplaza las validaciones del backend. La API sigue siendo la fuente de verdad.

Email local

CentralForms usa SMTP para enviar notificaciones basadas en submissions. En local se usa Mailpit:

Configuración	Valor
Host	localhost
Puerto	1025
SSL	false
FromEmail	no-reply@centralforms.local
FromName	CentralForms Dev

Las plantillas HTML de correo deben priorizar compatibilidad con clientes reales de email: tablas HTML, estilos inline mínimos y evitar CSS moderno dependiente del navegador.

Consideraciones técnicas

Tema	Criterio
LocalDB	Solo local. No usar con IIS.
SQL Server real	Requerido para QA, staging o producción.
Swagger	Habilitado en desarrollo; restringir o deshabilitar en producción.
Secretos	No versionar claves reales. Usar User Secrets, variables de entorno o mecanismo seguro.
API Keys	Almacenar hash, no valor plano.
CSRF	Stateful en base de datos. Se genera en GET y se consume en POST.
Email/Webhook	Integraciones asíncronas. Revisar resultado en IntegrationLogs.