|
| 1 | +--- |
| 2 | +id: DOC-QA-GUIA-ESTRUCTURA |
| 3 | +estado: borrador |
| 4 | +propietario: lider-qa |
| 5 | +ultima_actualizacion: 2025-02-25 |
| 6 | +relacionados: ["CHECK-AUDIT-REST", "DOC-QA-001"] |
| 7 | +--- |
| 8 | +# Guía rápida para nuevas guías de QA |
| 9 | + |
| 10 | +Esta guía toma como referencia `checklist_auditoria_restricciones.md` para documentar la estructura mínima y las convenciones de nomenclatura que deben cumplir las futuras guías de QA. |
| 11 | + |
| 12 | +## Mapeo del archivo de referencia |
| 13 | +- **Metadatos YAML**: `id`, `tipo`, `categoria`, `version`, `fecha_creacion`, `propietario`, `relacionados`. |
| 14 | +- **Encabezados principales** (en mayúsculas): Propósito, CÓMO USAR ESTE CHECKLIST, SECCIÓN 1 (restricciones críticas) con subsecciones numeradas, SECCIÓN 2 y SECCIÓN 3, RECURSOS Y REFERENCIAS, HISTORIAL DE AUDITORÍAS, FIRMA DE APROBACIÓN. |
| 15 | +- **Secciones clave**: |
| 16 | + - Objetivo: se expone en “Propósito”. |
| 17 | + - Alcance: descrito en la sección de uso y en los bloques de restricciones (alcances CRÍTICO/ALTA/MEDIA/BAJA). |
| 18 | + - Checklist: tablas numeradas por categoría (1.x, 2.x, 3.x) con columnas `#`, `Ítem`, `Verificación`, `Estado`, `Evidencia` y sumarios de puntaje. |
| 19 | + - Métricas: scoring mínimo y puntajes por sección (Score 1.x, Score 2.x, Score 3.x). |
| 20 | + - Responsables: roles explícitos en la firma de aprobación (QA Lead, Security Lead, Tech Lead). |
| 21 | + - Frecuencia: subsección “Frecuencia de Auditoría” dentro de CÓMO USAR ESTE CHECKLIST. |
| 22 | +- **Tablas**: usadas para checklist por sección, métricas de seguridad, recursos de archivos y firmas. Todas usan encabezados en mayúsculas y numeración alineada con el bloque (1.1, 1.2...). |
| 23 | +- **Nomenclatura**: IDs en mayúsculas con prefijos (ej. `CHECK-AUDIT-REST`), versiones semánticas, subtítulos numerados (`### 1.1 Comunicaciones [CRÍTICO]`), listas de acciones pendientes con casillas `[ ]`. |
| 24 | + |
| 25 | +## Elementos obligatorios para nuevas guías de QA |
| 26 | +1. **Metadatos YAML** con `id`, `estado`, `propietario`, `ultima_actualizacion`, `relacionados` y, si aplica, `tipo`, `categoria`, `version`, `fecha_creacion`. |
| 27 | +2. **Objetivo y alcance**: subsección corta que aclare propósito y límites del documento. |
| 28 | +3. **Frecuencia y responsables**: bloque dedicado a cuándo se ejecuta la guía y quién la aprueba (roles mínimos: QA Lead; agregar Security/Tech Lead cuando proceda). |
| 29 | +4. **Checklist estructurado**: |
| 30 | + - Numeración jerárquica por categoría (`1.x`, `2.x`, etc.). |
| 31 | + - Tablas con columnas `#`, `Ítem`, `Verificación`, `Estado`, `Evidencia`. |
| 32 | + - Cierre de cada subsección con puntaje o métricas de cumplimiento. |
| 33 | +5. **Métricas y criterios de aceptación**: metas mínimas (ej. puntuación global, cobertura ≥ 80 %) y umbrales por severidad. |
| 34 | +6. **Acciones pendientes**: lista de tareas o remediaciones con casillas `[ ]` vinculadas a cada sección. |
| 35 | +7. **Recursos y referencias**: enlaces a documentos relacionados y herramientas sugeridas. |
| 36 | +8. **Historial y firma**: tabla de auditorías previas y bloque de firmas para responsables. |
| 37 | +9. **Nomenclatura**: mantener IDs en mayúsculas con prefijos descriptivos (`CHECK-`, `DOC-`, `PLAN-`), subtítulos numerados y uso consistente de mayúsculas en encabezados principales. |
| 38 | + |
| 39 | +## Plantilla mínima sugerida |
| 40 | +```markdown |
| 41 | +--- |
| 42 | +id: CHECK-NNN |
| 43 | +estado: borrador |
| 44 | +propietario: rol-responsable |
| 45 | +ultima_actualizacion: AAAA-MM-DD |
| 46 | +relacionados: ["..."] |
| 47 | +--- |
| 48 | +# Título de la guía |
| 49 | + |
| 50 | +## Propósito y alcance |
| 51 | +- Objetivo |
| 52 | +- Alcance |
| 53 | + |
| 54 | +## Frecuencia y responsables |
| 55 | +- Frecuencia |
| 56 | +- Roles: QA Lead / Security Lead / Tech Lead |
| 57 | + |
| 58 | +## Checklist |
| 59 | +### 1.1 Tema [CRÍTICO] |
| 60 | +| # | Ítem | Verificación | Estado | Evidencia | |
| 61 | +|---|------|--------------|--------|-----------| |
| 62 | +| 1.1.1 | ... | ... | ... | ... | |
| 63 | + |
| 64 | +**Score 1.1**: X/X - Estado |
| 65 | + |
| 66 | +## Métricas y criterios |
| 67 | +- Puntuación mínima global |
| 68 | +- Criterios por severidad |
| 69 | + |
| 70 | +## Acciones pendientes |
| 71 | +- [ ] Acción |
| 72 | + |
| 73 | +## Recursos y referencias |
| 74 | +- ... |
| 75 | + |
| 76 | +## Historial de auditorías |
| 77 | +| Fecha | Auditor | Score Global | Estado | Notas | |
| 78 | +| --- | --- | --- | --- | --- | |
| 79 | + |
| 80 | +## Firma de aprobación |
| 81 | +- QA Lead: ___ Fecha: ___ |
| 82 | +- Security Lead: ___ Fecha: ___ |
| 83 | +- Tech Lead: ___ Fecha: ___ |
| 84 | +``` |
| 85 | + |
| 86 | +## Guía de QA: mapeo de referencia y estilo |
| 87 | + |
| 88 | +### 1. Archivo de referencia identificado |
| 89 | + |
| 90 | +- **Ruta:** `docs/standards/engineering-ruleset.md`. |
| 91 | +- **Propósito del archivo:** consolidar convenciones técnicas y de nomenclatura para el monorrepo (equivalente a un objetivo). |
| 92 | +- **Alcance explícito:** cubre estándares de repositorio, Bash, Python, UI y automatización; aplica a todo `docs/` y a las capas descritas (presentación, dominio, infraestructura). |
| 93 | + |
| 94 | +### 2. Mapa de estructura del archivo de referencia |
| 95 | + |
| 96 | +| Orden | Encabezado / sección | Contenido clave | Elementos relevantes para QA | |
| 97 | +| --- | --- | --- | --- | |
| 98 | +| 1 | Título y resumen inicial | Presenta el propósito del ruleset y su carácter viviente. | Objetivo y alcance implícitos. | |
| 99 | +| 2 | `1. Core Principles` | Lista numerada con principios base. | Actúa como checklist de lineamientos generales. | |
| 100 | +| 3 | `2. Repository Structure Expectations` | Diagrama de árbol del monorrepo con comentarios. | Define alcance y dependencias. | |
| 101 | +| 4 | `3. Naming Conventions` | Tabla con convenciones por capa (Bash, Python, React, SCSS, Webpack, PlantUML). | Convenciones de nomenclatura obligatorias. | |
| 102 | +| 5 | `4. Layering Rules` | Lista numerada con límites de responsabilidad. | Checklist de responsabilidades y restricciones. | |
| 103 | +| 6 | `5. Bash Standards` | Bullets de prácticas obligatorias. | Lista de verificación para scripts. | |
| 104 | +| 7 | `6. Python (Flask + PyTM) Standards` | Bullets de estilo y organización. | Lista de verificación por lenguaje. | |
| 105 | +| 8 | `7. PlantUML and Diagram Automation` | Bullets sobre ubicación y generación de diagramas. | Checklist especializado. | |
| 106 | +| … | Secciones posteriores | Continúan con estándares por capa (no visibles en este extracto). | Extienden checklists y reglas específicas. | |
| 107 | + |
| 108 | +#### Convenciones de nomenclatura derivadas |
| 109 | + |
| 110 | +- Usar `snake_case` para scripts Bash y módulos/funciones Python. |
| 111 | +- Emplear `PascalCase` para clases Python y componentes React. |
| 112 | +- Archivos SCSS en `kebab-case`, variables en `$kebab-case`. |
| 113 | +- Configuraciones de Webpack como `webpack.<target>.config.js`. |
| 114 | +- Plantillas PlantUML en `snake_case.puml`. |
| 115 | + |
| 116 | +### 3. Guía de estilo para nuevas guías de QA |
| 117 | + |
| 118 | +Al crear futuras guías de QA en este repositorio, incluye como mínimo: |
| 119 | + |
| 120 | +1. **Portada breve:** título, versión, fecha y sistema o equipo al que aplica. |
| 121 | +2. **Objetivo:** párrafo que explique qué se valida o protege. |
| 122 | +3. **Alcance:** listado con límites (incluye/excluye). Si aplica a un módulo específico, referéncialo. |
| 123 | +4. **Responsables:** tabla con rol, responsabilidad y contacto/canal. |
| 124 | +5. **Frecuencia:** periodicidad de ejecución (por ciclo, semanal, por release) y disparadores. |
| 125 | +6. **Checklist operativo:** tabla `| Paso | Acción | Evidencia esperada | Estado |` para asegurar trazabilidad. |
| 126 | +7. **Métricas:** tabla mínima `| Métrica | Definición | Umbral | Fuente |`. |
| 127 | +8. **Convenciones de nomenclatura:** referencias a la tabla del archivo de referencia y reglas específicas de QA (p. ej., prefijos para casos de prueba). |
| 128 | +9. **Registro de decisiones/observaciones:** bullets con hallazgos, desvíos y acciones correctivas. |
| 129 | +10. **Trazabilidad y anexos:** enlaces relativos a scripts, pipelines o plantillas utilizadas. |
| 130 | + |
| 131 | +#### Reglas de formato |
| 132 | + |
| 133 | +- Mantén encabezados numerados para reflejar orden y facilitar auditorías. |
| 134 | +- Usa tablas para checklist, métricas y responsables; alinea columnas con `|` para lecturabilidad. |
| 135 | +- Coloca código o comandos en bloques de triple acento invertido con idioma cuando aplique. |
| 136 | +- Nombra archivos de QA en `kebab-case` (`control-versionado-qa.md`) y rutas bajo `docs/gobernanza/qa/`. |
| 137 | +- Si introduces nuevas convenciones, documenta el objetivo y enlaza al recurso correspondiente dentro del repositorio. |
| 138 | + |
| 139 | +### 4. Ubicación y nomenclatura confirmada |
| 140 | + |
| 141 | +- No existen variantes previas (`.md`, `.adoc`, `.pdf`) de las guías solicitadas bajo `docs/` o `infrastructure/`. |
| 142 | +- Se crean y consolidan las rutas acordadas para QA: |
| 143 | + - `docs/gobernanza/qa/QA-ANALISIS-RAMAS-001/QA-ANALISIS-RAMAS-001.md` para el control de ramas. |
| 144 | + - `docs/infraestructura/qa/QA-ANALISIS-ESTRUCTURA-INFRA-001/QA-ANALISIS-ESTRUCTURA-INFRA-001.md` para la estructura de infraestructura. |
0 commit comments