# 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.