Functional Specification Anatomy

Especificación funcional — anatomía y convenciones

Para qué existe. Define la forma de un documento funcional de módulo: el que lee negocio y operación, el que el cliente firma, y contra el que se mide el cumplimiento. Está destilado de tres especificaciones reales que comparten columna vertebral —abonos SPEI, portal de firmas y ledger— y sirve tanto para escribir una nueva como para evaluar una que llega de fuera.

Cuándo aplica. Un módulo funcional con reglas de negocio que alguien ajeno al equipo tiene que validar y aprobar. No aplica a una decisión puntual —eso es adr.md— ni a la arquitectura de plataforma —eso es arch-doc-spec.md.

Guía compañera: spec-trazabilidad.md — qué se hace con el documento una vez existe: auditar, versionar y repartir lo que falta.

1. Anatomía

Tres bloques antes de la numeración, un núcleo variable y un cierre fijo.

Antes de numerar

Columna vertebral

Las dos que más se omiten son las dos que más cuestan después: sin matriz de trazabilidad no se puede auditar, y sin casos de uso no se puede probar. De las tres specs destiladas, la del ledger no tiene ninguna de las dos — y es justo la que sigue sin código.

El núcleo se organiza como el dominio pida. Si el flujo tiene fases con dueños distintos, organizarlo por fases: eso hace que el reparto por dueño salga solo cuando haya que auditarlo.

2. Bloque de metadatos

1
## Metadata
2

3
- **Componente**: <sistema y subsistema al que pertenece>
4
- **Alcance**: <una línea, con la frontera explícita: hasta dónde llega>
5
- **Entidad**: <la organización, con su identificador regulatorio si lo tiene>
6
- **Documentos relacionados**: <otros funcionales, por nombre corto>
7
- **Última actualización**: <AAAA-MM-DD>

El campo Alcance dice hasta dónde llega, no de qué trata. “abono SPEI tipo 1, extremo a extremo, hasta la frontera Rechazada” informa; “el proceso de abonos” no.

3. Guía de identificadores — la tabla que no es opcional

Toda spec abre con una tabla de prefijos, con una columna en lenguaje llano:

<CTX> son dos o tres letras del módulo (AB abonos, PF portal de firmas). Las secuencias propias del dominio —pasos de un pipeline, filas de un catálogo de resultados— se definen en la misma tabla.

La columna «en palabras simples» es el corazón de la convención. Un identificador sin su referente no informa a nadie; la tabla es lo que lo evita en el documento, y la misma regla aplica después en los tickets y en el daily.

Identificadores estables

Nunca se renumera. Al insertar un requisito entre dos existentes se añade sufijo de letra: RF-AB-02a, CA-AB-05a, RF-AB-05b. Renumerar invalida todas las citas en código, tests, commits, ADR y matrices de cobertura.

Un identificador retirado no se reutiliza. Su número muere con él.

La trampa: cambio de significado sin cambio de nombre

S-05 era el contrato de respuesta en la v19 de abonos y es la ventana de retención del duplicado en la v20. Mismo nombre, otra cosa. Cuando se publica una versión nueva, el documento dice explícitamente qué identificadores cambiaron de significado, aunque no cambien de nombre. Sin eso, quien audita lee mal y no se entera.

4. Alcance y fuera de alcance

Las dos mitades, siempre. El fuera de alcance es la mitad que evita el trabajo que nadie pidió, y se escribe con el motivo:

1
- Devoluciones y retornos: quedan fuera de v1. Sus causas viven en un catálogo aparte que esta
2
  versión no usa.

Si una regla del documento cita un catálogo o un flujo que está fuera de alcance, dilo donde lo citas. Es donde el lector va a dudar.

5. Criterios de aceptación

Formato: casilla, identificador en negrita, y el paso del pipeline entre paréntesis si lo tiene.

1
- [ ] **CA-AB-12** (V8): con el mismo hash de payload ya usado y vigente dentro de la ventana de
2
      retención (S-05), el resultado tiene `codigo`=**2030**, `descripcion`="Deposito duplicado."
3
      (HTTP 400).

Qué lo hace verificable:

Agrupa por fase o por etapa del flujo. El orden del pipeline es él mismo un criterio —cuál falla primero cuando fallan varios— y se escribe aparte.

Mal: “el sistema debe ser idempotente”. No se puede verificar sin volver a preguntar qué significa.

6. Matriz de trazabilidad

Una fila por RF y por RNF:

La columna Origen / Fuente es la que casi nadie pone y la que más vale. Distingue cuatro procedencias que se tratan distinto:

Sin esta columna, seis meses después nadie sabe si un requisito raro lo pidió el cliente o nos lo inventamos.

7. Matriz de responsabilidades

Por sección completa, no por requisito: quién solicita, quién valida, quién aprueba.

Dos reglas:

• Si las áreas se infirieron del contenido en vez de salir de un catálogo de roles acordado, el documento lo dice y lo marca como pendiente de confirmar. Una matriz inferida que se presenta como acordada es peor que no tenerla.
• Esta matriz es la fuente de autoridad sobre quién decide qué. Cuando después haya que repartir huecos por dueño, se cita, no se reinventa.

8. Supuestos de implementación

S-XX: una definición que la versión adopta porque aún no está cerrada formalmente con el cliente. Explícitos, numerados y con su condición de revisión.

1
- **S-05**: la ventana de retención del hash de duplicados es de N días. Valor pendiente de
2
  confirmar con el cliente; si cambia la definición, se revisa este supuesto y los criterios que
3
  lo citan (CA-AB-12, CA-AB-14).

Un supuesto que nadie cita desde ningún criterio probablemente no hacía falta. Un supuesto citado por tres criterios es un riesgo concentrado: si cae, caen los tres.

Un supuesto no es un bloqueo. El supuesto permite avanzar con una definición provisional; el bloqueo (B-) impide avanzar. Confundirlos hace que el equipo se pare donde podía seguir, o siga donde debía parar.

9. Anti-patrones

10. Checklist antes de circular

• Metadata completa, con el alcance como frontera, no como tema
• Guía de identificadores, con columna en lenguaje llano
• Alcance y fuera de alcance, cada exclusión con su motivo
• Estados y ciclo de vida, con tabla de transiciones
• Cada CA es verificable sin preguntar nada: condición, resultado, valores literales
• Cada RF/RNF aparece en la matriz de trazabilidad, con origen y CA que lo prueban
• Cada UC tiene su HU y viceversa
• Cada S- dice qué lo revisa y qué criterios caen con él
• Ningún identificador renumerado respecto de la versión anterior
• Los que cambiaron de significado sin cambiar de nombre están señalados
• Catálogos externos citados con nombre de fichero y hoja, listados en anexos