Initial commit

AGENTS_DATABASE_ERROR_LOGGING.md

@@ -0,0 +1,63 @@
+# Reglas obligatorias para registrar errores de base de datos
+
+Estas reglas complementan `AGENTS.md`, `AGENTS_STORED_PROCEDURES.md` y `AGENTS_DATA_READER_MAPPING.md`.
+
+## Información requerida
+
+Cuando falle una llamada a un procedimiento almacenado, el log técnico debe incluir:
+
+- Nombre completo del procedimiento, incluyendo esquema.
+- Nombre de cada parámetro.
+- Valor recibido por cada parámetro de entrada.
+- Tipo y valor disponible de los parámetros de salida.
+- Mensaje y número de la excepción SQL.
+- Un bloque `ReplaySql` que pueda copiarse en SQL Server para reproducir la llamada.
+
+Formato mínimo:
+
+```text
+StoredProcedure: dbo.PA_Modulo_Accion
+Parametros:
+@CveProyecto=-1
+@CvePeriodo=0
+@EsSimulador=0
+ReplaySql:
+DECLARE @ErrorMostrar varchar(max);
+DECLARE @ErrorTipo int;
+DECLARE @Return bit;
+EXEC [dbo].[PA_Modulo_Accion]
+    @CveProyecto = -1,
+    @CvePeriodo = 0,
+    @EsSimulador = 0,
+    @ErrorMostrar = @ErrorMostrar OUTPUT,
+    @ErrorTipo = @ErrorTipo OUTPUT,
+    @Return = @Return OUTPUT;
+SELECT @ErrorMostrar, @ErrorTipo, @Return;
+```
+
+## Seguridad
+
+- Nunca registrar valores de contraseñas, hashes, tokens, secretos, API keys ni cadenas de conexión.
+- Sustituir esos valores con `[REDACTADO]` tanto en `Parametros` como en `ReplaySql`.
+- El SQL reproducible con valores redactados requiere que el desarrollador proporcione manualmente un valor seguro de prueba.
+- Escapar comillas simples y generar literales SQL válidos.
+- Limitar textos extensos y marcar el valor como truncado.
+- No mostrar `ReplaySql`, parámetros ni detalles técnicos al usuario final.
+- Los datos técnicos sólo deben escribirse en el archivo log protegido de la aplicación.
+
+## Implementación
+
+- Configurar todos los comandos mediante `StoredProcedureCommand` para que `StoredProcedureDiagnostics` capture el contexto.
+- `DbExecutor` debe adjuntar el diagnóstico al log en `SqlException`, timeout, error de salida del PA y excepciones inesperadas.
+- Limpiar el contexto de diagnóstico en `finally` para impedir que parámetros de una petición aparezcan en otra.
+- Usar `AsyncLocal` para aislar correctamente solicitudes concurrentes y operaciones asíncronas.
+- Capturar los parámetros OUTPUT después de cerrar el `DataReader`.
+- No establecer `SqlConnection.FireInfoMessageEventOnUserErrors = true`; esa opción transforma errores SQL de severidad 11–16 en eventos informativos y puede ocultar la excepción real.
+- Los mensajes `RAISERROR` de severidad 10 pueden registrarse mediante `SqlConnection.InfoMessage` sin activar esa opción.
+- Si `@Return`, `@ErrorTipo` y `@ErrorMostrar` regresan sin valor, registrar que la versión instalada del PA no devolvió el contrato requerido.
+
+## Alcance
+
+- Registrar parámetros detallados sólo cuando exista un error o advertencia que requiera diagnóstico.
+- No registrar cada ejecución exitosa de manera predeterminada.
+- No usar el log como auditoría de operaciones exitosas; la auditoría pertenece a su propio contrato o procedimiento.