Especificaciones

Índice y convenciones

docs/05-especificaciones/README.md · 120 líneas

Especificaciones — MVP 1

Estado: Borrador · Última actualización: 2026-08-24 Deriva de: casos de uso, reglas de negocio, requerimientos funcionales · Decisiones: DEC-059 (resuelve PA-002)

1. Qué es esta carpeta

Las especificaciones de desarrollo del MVP 1, agrupadas por historias de usuario (HU-###). Cada HU aterriza un caso de uso o un comportamiento transversal en algo construible por un developer: enunciado, alcance, comportamiento, reglas, permisos, datos funcionales y criterios de aceptación verificables (CA-###, estilo Gherkin).

Lo que estas specs NO incluyen (fuera de alcance por decisión, no por olvido):

Diseño técnico: modelo de datos, esquema de tablas, contratos de API, arquitectura.
Plan / backlog priorizado: orden, estimación y secuencia de construcción.
Contratos de integración detallados: las integraciones con sistemas externos

(Argos Operaciones, JWT de Flagare, notifications.flagare/SSE, S3, Bedrock/IA, GitLab) quedan documentadas a nivel funcional —qué se toca y cuándo—, no diseñadas. El developer sabe implementarlas; el contrato fino se cierra cuando se respondan las preguntas abiertas correspondientes.

2. Cómo leer una HU

Cada historia sigue esta plantilla. Las secciones que no apliquen se omiten.

Sección	Qué contiene
Cabecera de trazabilidad	Épica · Deriva de (CU o Transversal) · Cubre (RF) · Reglas (RN) · Decisiones (DEC) · Estado
Historia	`Como <rol>, quiero <capacidad>, para <valor>`
Objetivo / valor	Por qué existe, en una o dos líneas
Alcance	Qué entra y qué queda fuera de esta HU
Actores y permisos	Qué puede hacer cada rol involucrado
Precondiciones	Estado necesario antes de ejecutar
Comportamiento funcional	Flujo principal, alternativos y de error, en prosa concisa
Datos y campos	Campos funcionales (qué se captura / precarga), sin esquema
Reglas de negocio aplicables	Las RN que gobiernan, reenunciadas en su efecto
Estados y transiciones	Referencia a la máquina de estados cuando aplica
Integraciones	Sistemas externos que se tocan, a nivel funcional (documentado, no diseñado)
Eventos que emite	Eventos de dominio disparados
Criterios de aceptación	`CA-###` en Gherkin `Dado / Cuando / Entonces`, verificables
Dependencias y bloqueos	`PA-###` que la condicionan y otras `HU-###` relacionadas
Casos borde / notas	Lo que no cabe arriba y no debe perderse

3. Convenciones de identificadores

Prefijo	Artefacto	Ejemplo
`HU-###`	Historia de usuario (lleva su especificación)	`HU-016`
`CA-###`	Criterio de aceptación	`CA-138`

Los IDs son estables: no se reutilizan ni se renumeran. Los CA-### se numeran por bandas de épica; que haya saltos entre bandas es esperado, no un hueco.

4. Épicas

Las épicas reutilizan los trece bloques funcionales A–M de los requerimientos funcionales.

Épica	Archivo	Historias
A · Autenticación, usuarios y roles	ep-a-autenticacion-usuarios-roles.md	HU-001, HU-002
B · Gestión de proyectos	ep-b-gestion-proyectos.md	HU-003, HU-004, HU-005
C · Ingesta de requerimientos	ep-c-ingesta-requerimientos.md	HU-006
D · Casos de uso	ep-d-casos-de-uso.md	HU-007 a HU-011
E · Plan de pruebas y escenarios	ep-e-plan-y-escenarios.md	HU-012, HU-013
F · Ambientes de prueba	ep-f-ambientes.md	HU-014
G · Ciclos y ejecución	ep-g-ciclos-y-ejecucion.md	HU-015 a HU-018
H · Evidencia	ep-h-evidencia.md	HU-019
I · Bugs y bloqueos	ep-i-bugs-y-bloqueos.md	HU-020, HU-021
J · Observabilidad y reportes	ep-j-observabilidad-y-reportes.md	HU-022, HU-023, HU-024
K · Eventos y notificaciones	ep-k-eventos-y-notificaciones.md	HU-025
L · Orquestación de IA	ep-l-orquestacion-ia.md	HU-026
M · Auditoría y trazabilidad	ep-m-auditoria-y-trazabilidad.md	HU-027

5. Inventario de historias y trazabilidad

Cada CU del MVP tiene al menos una HU; los bloques transversales (sin CU de actor) también quedan cubiertos.

HU	Título	Épica	Deriva de	Cubre RF	Reglas RN
HU-001	Autenticarse con el JWT de Flagare	A	Transversal	RF-001–003	RN-008
HU-002	Gestionar miembros y roles del proyecto	A	CU-002	RF-004–008, RF-018	RN-001–007
HU-003	Importar un proyecto desde Argos Operaciones	B	CU-001	RF-009–012, RF-017	RN-014, RN-015
HU-004	Sincronizar y degradar con Argos Operaciones	B	Transversal	RF-013, RF-014	RN-016, RN-017
HU-005	Archivar y reactivar un proyecto	B	Transversal	RF-016, RF-138, RF-141	RN-005
HU-006	Cargar un requerimiento	C	CU-003	RF-019–024	RN-018, RN-019
HU-007	Analizar un requerimiento con IA	D	CU-004	RF-025–028, RF-124, RF-126, RF-127, RF-130	RN-064, RN-066, RN-068
HU-008	Generar casos de uso con IA	D	CU-005	RF-029, RF-031, RF-032, RF-124, RF-126	RN-020, RN-021, RN-064
HU-009	Crear un caso de uso manualmente	D	CU-006	RF-030–032	RN-020, RN-021, RN-065
HU-010	Revisar y congelar un caso de uso	D	CU-007	RF-033–037, RF-041, RF-042	RN-009, RN-022, RN-025
HU-011	Crear una versión nueva de un caso congelado	D	CU-008	RF-038–040, RF-042	RN-023, RN-024, RN-037
HU-012	Generar el plan de pruebas y sus escenarios	E	CU-009	RF-043–050, RF-054–056, RF-139	RN-031, RN-032, RN-036
HU-013	Aprobar el plan de pruebas	E	CU-010	RF-051–053	RN-033–035
HU-014	Registrar y preparar un ambiente de prueba	F	CU-011	RF-057–067	RN-012, RN-026–030
HU-015	Abrir un ciclo de QA	G	CU-012	RF-066–069	RN-028, RN-029
HU-016	Ejecutar un escenario de forma guiada	G	CU-013	RF-070–076, RF-079, RF-083–088	RN-013, RN-038, RN-040, RN-042, RN-043, RN-046, RN-047
HU-017	Ejecutar un escenario fuera de ciclo	G	CU-013 (A1)	RF-070, RF-071	RN-038, RN-062, RN-080
HU-018	Reejecutar tras una corrección	G	CU-016	RF-079, RF-080, RF-098, RF-099	RN-040, RN-041, RN-044, RN-055
HU-019	Capturar y conservar evidencia	H	Transversal	RF-089–091	RN-010, RN-046–050
HU-020	Registrar un bug desde un fallo	I	CU-014	RF-077, RF-092–100	RN-051–054, RN-056, RN-083
HU-021	Registrar y resolver un bloqueo	I	CU-015	RF-078, RF-101–105, RF-140	RN-039, RN-057, RN-058
HU-022	Cerrar el ciclo y emitir el reporte de calidad	J	CU-017	RF-081, RF-082, RF-106–113	RN-045, RN-059, RN-060, RN-062, RN-063
HU-023	Consultar el dashboard de cobertura y avance	J	Transversal	RF-106–112, RF-115, RF-116	RN-059, RN-060, RN-062
HU-024	Consultar el reporte agregado como Client	J	CU-018	RF-006, RF-015, RF-114	RN-004, RN-006, RN-061
HU-025	Emitir eventos de dominio y notificar	K	Transversal	RF-117–123	RN-069–072
HU-026	Orquestar las operaciones de IA	L	Transversal	RF-125, RF-128–130	RN-064–068
HU-027	Registrar auditoría e integridad referencial	M	Transversal	RF-131–137	RN-011, RN-073–076

6. Estado de cobertura

18/18 casos de uso con al menos una HU.
Bloques transversales (autenticación, sincronización, evidencia, eventos, IA,

auditoría) cubiertos por HU propias, aunque no deriven de un CU de actor.

Quedan fuera del MVP los ítems marcados [Fase 2]+ en los requerimientos

(Playwright, grabación de pantalla, RAG/pgvector, ingesta binaria, etc.).