> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/docs/known_warnings.md).

# Warnings Conocidos y Aceptados

***

## 🚨 Incidente de Seguridad — 23 abril 2026

**Clave API de Gemini expuesta en historial git**

* La clave anterior fue encontrada en 3 commits del historial git.
* Acción tomada: **Revocada y reemplazada** por una nueva clave segura configurada únicamente a través de la variable de entorno `GEMINI_API_KEY` en el archivo `.env` (el cual no está comiteado en Git).
* Recomendación: Si el repo fue público, considerar la clave anterior como comprometida y monitorear uso indebido.

**Contraseñas hardcodeadas en seeders**

* Los seeders `FoundersSeeder` y `UsuarioAdminSeeder` contienen contraseñas en texto plano (`Senselab2024!`, `admin123`).
* Acción sugerida: Usar variables de entorno para las contraseñas en seeders y regenerar en producción.
* Riesgo: Si los seeders se ejecutan en producción sin cambio, cualquier persona con acceso al código conoce las credenciales iniciales.

***

**Última actualización:** 23 de abril de 2026\
**Versión del proyecto:** 5.0.2\
**Tests pasando:** ✅ 1261/1261 (5 skipped) — \~3,500 assertions\
**PHPStan:** ✅ Level 8 — 0 errores en 687 archivos\
**Impacto en funcionalidad:** ❌ Ninguno

***

## 📖 Propósito de este Documento

Este documento registra todos los warnings de análisis estático que son **conocidos, revisados y aceptados** por el equipo de desarrollo. Estos warnings NO representan errores de funcionalidad y el código opera correctamente.

### ¿Por qué existen estos warnings?

Los analizadores de código estático como SonarQube aplican reglas genéricas que a veces generan "falsos positivos" en contextos específicos:

* **Anotaciones OpenAPI/Swagger**: Requieren strings literales repetidos por diseño
* **Rutas de Laravel**: El patrón REST CRUD repite paths para diferentes métodos HTTP
* **Convenciones de framework**: Laravel tiene patrones que difieren de aplicaciones genéricas

***

## 🔍 Categorías de Warnings

### 1. S1192 - String Literals Duplicated (\~550 warnings)

**Regla SonarQube:** `php:S1192`\
**Descripción:** Define a constant instead of duplicating this literal X times.

#### 1.1 Anotaciones OpenAPI en Controllers

| Tipo de String  | Ejemplo                                       | Motivo de Aceptación                         |
| --------------- | --------------------------------------------- | -------------------------------------------- |
| Tags de API     | `'Empresas'`, `'Ventas'`                      | Requerido por Swagger para agrupar endpoints |
| Schemas         | `'#/components/schemas/Empresa'`              | Referencias a modelos OpenAPI                |
| Respuestas HTTP | `'Error del servidor'`, `'No autenticado'`    | Mensajes estándar de respuesta               |
| Descriptions    | `'ID de la empresa'`, `'Venta no encontrada'` | Documentación de parámetros                  |
| Paths           | `'/api/ventas/{id}'`                          | Definición de rutas para OpenAPI             |

**Archivos afectados:**

* `app/Http/Controllers/API/EmpresaController.php` (\~7 warnings)
* `app/Http/Controllers/API/VentaController.php` (\~7 warnings)
* `app/Http/Controllers/API/ClienteController.php` (\~5 warnings)
* `app/Http/Controllers/API/ProductoController.php` (\~5 warnings)
* `app/Http/Controllers/API/EntradaInventarioController.php` (\~5 warnings)
* `app/Http/Controllers/API/MovimientoBancarioController.php` (\~3 warnings)
* `app/Http/Controllers/API/OrdenCompraController.php` (\~2 warnings)
* ... y \~75 controllers más

**Total estimado:** \~400 warnings en Controllers

#### 1.2 Rutas en `routes/api/`

| Tipo de String       | Ejemplo                   | Motivo de Aceptación                               |
| -------------------- | ------------------------- | -------------------------------------------------- |
| Paths con parámetros | `'/empresas/{empresa}'`   | Convención REST (GET, PUT, DELETE usan mismo path) |
| Paths de recursos    | `'/productos/{producto}'` | Patrón estándar Laravel Resource Routes            |

**Archivos afectados:** 14 archivos en `routes/api/` (particionados por módulo)

**Total estimado:** \~80 warnings en routes/

***

### 2. S138 - Function Too Long (YA NO APLICA ✅)

**Regla SonarQube:** `php:S138`\
**Estado anterior:** 1 warning en `routes/api.php` (775 líneas).\
**Estado actual:** ✅ **Resuelto** — Las rutas fueron particionadas en 14 archivos independientes bajo `routes/api/`. El archivo `routes/api.php` principal ahora tiene solo 81 líneas.

La regla de supresión S138 permanece en `sonar-project.properties` como precaución.

***

### 3. PHPUnit Metadata Deprecation Warnings (\~367 warnings)

**Tipo:** Deprecation Warning de PHPUnit 12\
**Descripción:** Metadata found in doc-comment. Metadata in doc-comments is deprecated and will no longer be supported in PHPUnit 12.

**Motivo:** 41 clases de test usan anotaciones `@test` en doc-comments en lugar de atributos PHP 8 (`#[Test]`).

**Archivos afectados (41 clases):**

* `tests/Unit/Helpers/` — ArrayHelpersTest, StringHelpersTest
* `tests/Unit/Services/` — ClaveNumericaGeneratorTest, RateLimiterTest, XadesEpesSignerTest, XmlComprobanteBuilderTest
* `tests/Unit/Services/Hacienda/` — HaciendaApiClientTest y otros
* `tests/Unit/Validation/` — \~30 clases de validación
* `tests/Feature/` — ComprobanteElectronicoControllerTest, FacturacionElectronica\*, Hacienda/\*

**Impacto:** Ninguno funcional. Los tests ejecutan correctamente.

**Acción futura:** Migrar anotaciones `@test` a atributos `#[Test]` cuando se actualice a PHPUnit 12.

***

## ⚙️ Configuración de Supresión

### SonarQube Server (`sonar-project.properties`)

```properties
# Reglas ignoradas por contexto específico
sonar.issue.ignore.multicriteria=e1,e2,e3,e4,e5,e6

# S1192 en Controllers (OpenAPI annotations)
sonar.issue.ignore.multicriteria.e4.ruleKey=php:S1192
sonar.issue.ignore.multicriteria.e4.resourceKey=**/Controllers/**

# S1192 en routes (Laravel convention)
sonar.issue.ignore.multicriteria.e5.ruleKey=php:S1192
sonar.issue.ignore.multicriteria.e5.resourceKey=**/routes/**

# S138 en routes (large route files)
sonar.issue.ignore.multicriteria.e6.ruleKey=php:S138
sonar.issue.ignore.multicriteria.e6.resourceKey=**/routes/**
```

### SonarLint Local (`.sonarlint/settings.json`)

```json
{
  "rules": {
    "php:S1192": { "level": "off" },
    "php:S138": { "level": "off" }
  }
}
```

***

## 📊 Resumen Ejecutivo

| Categoría                      | Cantidad | Severidad  | Estado                             |
| ------------------------------ | -------- | ---------- | ---------------------------------- |
| S1192 en Controllers (OpenAPI) | \~400    | ⚪ Info     | Suprimido en SonarQube             |
| S1192 en routes (REST paths)   | \~80     | ⚪ Info     | Suprimido en SonarQube             |
| S138 en routes/api.php         | 0        | ✅          | **Resuelto** (rutas particionadas) |
| PHPUnit Metadata Deprecation   | \~367    | 🟡 Warning | Migrar en PHPUnit 12               |
| PHPStan errores                | 0        | ✅          | Level 8, 0 errores                 |

***

## ✅ Verificación de Estado del Código

```bash
# Tests automatizados
php artisan test
# Resultado: 997 passed, 5 skipped, ~3500 assertions ✅

# PHPStan nivel 8
vendor/bin/phpstan analyse app/ --level=8
# Resultado: [OK] No errors (687 archivos) ✅
```

***

## 📅 Historial de Revisiones

| Fecha      | Revisado Por        | Notas                                                               |
| ---------- | ------------------- | ------------------------------------------------------------------- |
| 2026-03-24 | Jeremy Arias Solano | Actualización v3.3.0 — 997 tests, mismos warnings aceptados         |
| 2026-03    | Jeremy Arias Solano | Reescritura completa — v2.8.0, rutas particionadas, PHPStan Level 8 |
| 2025-12-05 | GitHub Copilot      | Creación inicial del documento                                      |

***

## 🔄 Política de Actualización

Este documento debe actualizarse cuando:

1. Se agreguen nuevos controllers con anotaciones OpenAPI
2. Se modifique significativamente el archivo de rutas
3. Se actualice a una versión mayor de PHPUnit
4. Se agreguen nuevas reglas de supresión en SonarQube
5. Se resuelva algún warning listado aquí

***

**Nota:** Los warnings aquí documentados NO son bugs ni vulnerabilidades de seguridad. Son sugerencias de mejora de código que, en el contexto específico de este proyecto (Laravel API con Swagger), representan falsos positivos o decisiones de diseño aceptadas. Pero si en algún momento se decide refactorizar para eliminar estos warnings, se debe actualizar este documento y la configuración de supresión correspondiente.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/docs/known_warnings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.