08
Estilos, tácticas y decisiones

Repaso y examen parcial

Estilos, tácticas y decisiones

Semana 8 — Repaso y examen parcial

Objetivos

  • Repasar las partes 1 y 2 del curso (semanas 1 a 7) y conectar sus ideas en un mismo caso: de los requisitos de un sistema a una arquitectura decidida, documentada y evaluada.
  • Resolver problemas del tipo del examen: escribir escenarios, calcular con percentiles y disponibilidad, analizar un grafo de dependencias, comparar estilos, elegir tácticas, escribir un ADR y evaluar un diseño.
  • Revisar las decisiones de su propio P2 con los criterios de las semanas 2 a 7 y poder defender cada una con sus alternativas.

Sesión A — Repaso

Lecturas:

Lecturas complementarias:

  • Las lecturas principales que no hayan alcanzado a leer. Para el examen pesan más Software Architecture in Practice, cap. 1, 3, 8, 9 y 4; el artículo de Parnas, y el artículo de Nygard sobre los ADR.

Temas:

  • Semana 1 (1): arquitectura como estructuras para razonar y como decisiones que cuesta cambiar; estructuras de módulos, de componentes y conectores, y de asignación; requisitos significativos para la arquitectura, restricciones y stakeholders; los niveles de contexto y de contenedores de C4.
  • Semana 2 (2): el escenario de seis partes; percentiles y por qué no el promedio; disponibilidad, los nueves y la composición en serie; utility tree; trade-offs.
  • Semana 3 (3): el criterio de Parnas; ocultamiento de información, cohesión y acoplamiento; ciclos; inversión de dependencias; ports y adapters; reglas de dependencia que se comprueban.
  • Semana 4 (4): qué es un estilo; capas frente a modular monolith (partir por rol técnico o por dominio); pipeline; microkernel y el costo de un contrato.
  • Semana 5 (5): lo que cambia al cruzar la red y las falacias; service-based y microservicios; evento y comando; broker y mediator; cómo se elige un estilo con escenarios.
  • Semana 6 (6): táctica frente a patrón; tácticas de modificabilidad, de rendimiento (controlar la demanda, administrar los recursos), de disponibilidad (detectar, recuperarse, prevenir) y de seguridad (detectar, resistir, reaccionar, recuperarse); el trade-off de cada una.
  • Semana 7 (7): vistas y para quién; C4 y arc42; ADR con alternativas; las iteraciones de ADD; ATAM y sus resultados (riesgos, puntos de sensibilidad y de trade-off).
  • Ejercicios tipo examen, resueltos en clase sobre un caso nuevo (ni Tinkuy ni un sistema de entradas): un párrafo de requisitos → sus ASR y tres escenarios; una tabla de latencias → percentiles y lo que esconden; un grafo de dependencias → sus ciclos y cómo romper uno; dos estilos candidatos → cuál y a qué costo; un escenario → tres tácticas y su trade-off; una decisión → su ADR.
  • Error común: estudiar memorizando listas de tácticas o de estilos. El examen da un caso que no han visto y pide decidir y justificar; una respuesta que no dice qué se sacrifica está incompleta.

Sesión B — Examen parcial

Temas: partes 1 y 2 del curso, semanas 1 a 7. Formato y recomendaciones en exams/README.md.

Qué entra:

  • Fundamentos: distinguir decisiones de arquitectura de las que no lo son; leer un sistema en sus tres tipos de estructuras; separar ASR, requisitos funcionales y restricciones.
  • Atributos de calidad: escribir y corregir escenarios de seis partes; calcular percentiles y disponibilidad; armar y leer un utility tree; nombrar el trade-off de una decisión.
  • Modularidad: aplicar el criterio de Parnas a una división dada; reconocer formas de acoplamiento en un fragmento de TypeScript; encontrar un ciclo y romperlo con una inversión de dependencias; escribir una regla de dependencia.
  • Estilos: para un sistema descrito con sus escenarios y su equipo, comparar dos estilos y elegir uno, diciendo qué se pierde.
  • Tácticas: para un escenario, proponer tácticas del atributo correcto y decir qué otro atributo afecta cada una.
  • Decisiones y evaluación: escribir un ADR completo; dibujar un diagrama de contexto o de contenedores con sus reglas; recorrer un escenario sobre un diseño y clasificar lo que encuentren.

Qué no entra: los temas marcados con ✂️ que no se hayan visto en clase, y todo lo de las partes 3 y 4.

Laboratorio

No hay laboratorio esta semana. El tiempo se usa para cerrar P2.

Entregas

Preguntas de repaso

  1. Un sistema de reservas de citas médicas tiene estos requisitos: atiende 40 clínicas; un médico puede bloquear su agenda; los recordatorios salen por mensaje de texto; la ley exige guardar el historial diez años; se quiere agregar una clínica nueva en un día. Clasifiquen cada uno como requisito funcional, ASR o restricción.
  2. Escriban, para ese sistema, un escenario de disponibilidad y uno de modificabilidad, con sus seis partes.
  3. De 1 000 peticiones, 900 tardan 40 ms, 80 tardan 300 ms y 20 tardan 4 s. Calculen el promedio, el p50, el p95 y el p99. ¿Qué número le mostrarían a quien decide si hace falta una mejora?
  4. El módulo billing importa de patients y patients importa de billing. Describan dos formas de romper el ciclo y cuándo conviene cada una.
  5. El equipo son seis personas. Comparen un modular monolith y microservicios para ese sistema, con dos escenarios de su elección.
  6. Escriban el ADR de la decisión de la pregunta anterior.

Código de la semana

Compilar y probar dentro del contenedor del curso con make y make test.

Ejemplos (27)Errores (6)Pruebas (7)Compilación (3)

Ejemplos

Los programas que usan los apuntes y la clase.

availability.tsDescargar availability.ts
// Disponibilidad de una operación que necesita varias piezas.
//
// Una operación se describe como una cadena: una etapa por línea, y la
// operación necesita que respondan todas (en serie). Una etapa puede tener
// varias copias redundantes: basta con que responda una (en paralelo).
//
//   enlace de la agencia: 99.2 | 97
//   API central: 99.95
//
// Las dos cuentas suponen que las fallas son independientes. Las
// disponibilidades son fracciones entre 0 y 1: 99,9 % es 0.999.

export type Stage = { name: string; copies: number[] };

const HOURS_PER_YEAR = 365 * 24;
const MINUTES_PER_MONTH = 30 * 24 * 60;

function assertFraction(value: number): void {
  if (!(value >= 0 && value <= 1)) throw new RangeError(`La disponibilidad es una fracción entre 0 y 1: ${value}`);
}

/** En serie: la operación necesita a todas las partes. Se multiplican. */
export function inSeries(parts: readonly number[]): number {
  parts.forEach(assertFraction);
  return parts.reduce((product, part) => product * part, 1);
}

/** En paralelo: basta una copia. Falla solo si fallan todas a la vez. */
export function inParallel(copies: readonly number[]): number {
  if (copies.length === 0) throw new RangeError('Una etapa necesita al menos una copia');
  copies.forEach(assertFraction);
  return 1 - copies.reduce((product, copy) => product * (1 - copy), 1);
}

/** La disponibilidad de una etapa: la de sus copias en paralelo. */
export function stageAvailability(stage: Stage): number {
  return inParallel(stage.copies);
}

/** La disponibilidad de la operación: sus etapas en serie. */
export function chainAvailability(stages: readonly Stage[]): number {
  return inSeries(stages.map(stageAvailability));
}

/** Horas al año en que la operación no está disponible (año de 365 días). */
export function downtimeHoursPerYear(fraction: number): number {
  assertFraction(fraction);
  return (1 - fraction) * HOURS_PER_YEAR;
}

/** Minutos al mes en que no está disponible (mes de 30 días). */
export function downtimeMinutesPerMonth(fraction: number): number {
  assertFraction(fraction);
  return (1 - fraction) * MINUTES_PER_MONTH;
}

/**
 * Lee una cadena: "nombre: porcentaje" por línea, con las copias redundantes
 * separadas por |. Acepta coma o punto decimal. Las líneas vacías y las que
 * empiezan con # se ignoran.
 */
export function parseChain(text: string): Stage[] {
  const stages: Stage[] = [];
  text.split('\n').forEach((raw, index) => {
    const line = raw.trim();
    if (line === '' || line.startsWith('#')) return;
    const colon = line.lastIndexOf(':');
    const name = line.slice(0, colon).trim();
    const copies = line
      .slice(colon + 1)
      .split('|')
      .map((text) => Number(text.trim().replace(',', '.')));
    if (colon < 1 || name === '' || copies.some((copy) => !Number.isFinite(copy) || copy < 0 || copy > 100)) {
      throw new SyntaxError(`Línea ${index + 1}: se espera "nombre: porcentaje [| porcentaje]": ${line}`);
    }
    stages.push({ name, copies: copies.map((copy) => copy / 100) });
  });
  if (stages.length === 0) throw new SyntaxError('La cadena no tiene ninguna etapa');
  return stages;
}
check.tsDescargar check.ts
// Revisor de las cuentas de la semana 8. Tres usos:
//
//   node check.ts percentiles data/tracking-latencies.txt [otra-tabla.txt ...]
//       resumen de una tabla de frecuencias (cantidad y milisegundos por
//       línea); con varias tablas, las junta antes de calcular
//   node check.ts availability data/register-central.txt
//       disponibilidad de una operación: etapas en serie, copias en paralelo
//   node check.ts cycles data/modules.txt [--without "a -> b" ...]
//       ciclos de un grafo de dependencias; con --without, el grafo que queda
//       al quitar esas flechas
//
// Los percentiles se calculan por rango más cercano (ver latency.ts).

import { readFileSync } from 'node:fs';
import { chainAvailability, downtimeHoursPerYear, downtimeMinutesPerMonth, parseChain, stageAvailability } from './availability.ts';
import {
  buildGraph,
  elementaryCycles,
  formatCycle,
  formatEdge,
  parseEdges,
  smallestCuts,
  stability,
  tangles,
  topologicalOrder,
  withoutEdges,
} from './cycles.ts';
import { mean, parseTable, percentile, rank, spans, total } from './latency.ts';

function usage(): never {
  console.error('Uso: node check.ts percentiles <tabla>... | availability <cadena> | cycles <grafo> [--without "a -> b"]...');
  process.exit(2);
}

function percentiles(files: string[]): void {
  if (files.length === 0) usage();
  const rows = files.flatMap((file) => parseTable(readFileSync(file, 'utf8')));
  const n = total(rows);
  console.log(`n = ${n}`);
  console.log('posiciones     valor');
  for (const span of spans(rows)) {
    console.log(`${`${span.from} a ${span.to}`.padEnd(15)}${span.value} ms`);
  }
  console.log(`promedio = ${mean(rows).toFixed(1)} ms`);
  for (const p of [50, 90, 95, 99, 100]) {
    console.log(`${`p${p}`.padEnd(5)}posición ${String(rank(n, p)).padEnd(6)}${percentile(rows, p)} ms`);
  }
}

function percent(fraction: number): string {
  return `${(fraction * 100).toFixed(4)} %`;
}

function availability(files: string[]): void {
  const file = files[0] ?? usage();
  const stages = parseChain(readFileSync(file, 'utf8'));
  const width = Math.max(...stages.map((stage) => stage.name.length));
  for (const stage of stages) {
    const note = stage.copies.length > 1 ? `  (${stage.copies.length} copias en paralelo)` : '';
    console.log(`${stage.name.padEnd(width)}  ${percent(stageAvailability(stage))}${note}`);
  }
  const whole = chainAvailability(stages);
  console.log(`${'En serie'.padEnd(width)}  ${percent(whole)}`);
  console.log(`  no disponible al año: ${downtimeHoursPerYear(whole).toFixed(1)} h`);
  console.log(`  no disponible al mes: ${downtimeMinutesPerMonth(whole).toFixed(0)} min`);
}

function cycles(args: string[]): void {
  const file = args[0] ?? usage();
  const removed = [];
  for (let index = 1; index < args.length; index += 2) {
    if (args[index] !== '--without' || args[index + 1] === undefined) usage();
    removed.push(...parseEdges(args[index + 1]!));
  }
  let graph = buildGraph(parseEdges(readFileSync(file, 'utf8')));
  if (removed.length > 0) {
    graph = withoutEdges(graph, removed);
    console.log(`Sin ${removed.map(formatEdge).join(' ni ')}:`);
  }
  const edgeCount = [...graph.values()].reduce((sum, targets) => sum + targets.length, 0);
  console.log(`${graph.size} módulos, ${edgeCount} dependencias`);

  const found = elementaryCycles(graph);
  if (found.length === 0) {
    console.log('Sin ciclos.');
    console.log(`Orden posible (primero lo que no depende de nadie): ${topologicalOrder(graph)!.join(', ')}`);
  } else {
    console.log(`Ciclos: ${found.length}`);
    for (const cycle of found) console.log(`  ${formatCycle(cycle)}`);
    console.log('Módulos enredados (de cada uno se llega a todos los demás del grupo):');
    for (const group of tangles(graph)) console.log(`  ${group.join(', ')}`);
    const cuts = smallestCuts(graph);
    console.log(`Hay que quitar al menos ${cuts[0]!.length} ${cuts[0]!.length === 1 ? 'flecha' : 'flechas'}; formas de hacerlo: ${cuts.length}`);
    for (const cut of cuts) console.log(`  ${cut.map(formatEdge).join('  y  ')}`);
  }

  console.log('módulo         Ca  Ce  I');
  for (const row of stability(graph)) {
    const instability = `${Math.round(row.instability * 100)} %`;
    console.log(`${row.name.padEnd(15)}${String(row.dependents).padEnd(4)}${String(row.dependencies).padEnd(4)}${instability}`);
  }
}

const [command, ...args] = process.argv.slice(2);
try {
  if (command === 'percentiles') percentiles(args);
  else if (command === 'availability') availability(args);
  else if (command === 'cycles') cycles(args);
  else usage();
} catch (error) {
  if (error instanceof SyntaxError || error instanceof RangeError || (error as NodeJS.ErrnoException).code === 'ENOENT') {
    console.error((error as Error).message);
    process.exit(2);
  }
  throw error;
}
cycles.tsDescargar cycles.ts
// Ciclos en un grafo de dependencias entre módulos.
//
// El grafo se escribe como una lista de flechas, una por línea:
//
//   shipments -> tariffs
//
// que se lee "shipments depende de tariffs" (shipments importa algo de
// tariffs). Es el mismo sentido que usa dependency-cruiser. Las funciones son
// puras; los grafos de un examen son pequeños, así que se prefiere la versión
// más fácil de leer a la más eficiente.

export type Edge = { from: string; to: string };

/** Para cada módulo, la lista ordenada de módulos de los que depende. */
export type Graph = Map<string, string[]>;

const EDGE_LINE = /^(\S+)\s*->\s*(\S+)$/;

/** Lee una lista de flechas. Las líneas vacías y las que empiezan con # se ignoran. */
export function parseEdges(text: string): Edge[] {
  const edges: Edge[] = [];
  text.split('\n').forEach((raw, index) => {
    const line = raw.trim();
    if (line === '' || line.startsWith('#')) return;
    const match = EDGE_LINE.exec(line);
    if (!match) throw new SyntaxError(`Línea ${index + 1}: se espera "modulo -> modulo": ${line}`);
    edges.push({ from: match[1]!, to: match[2]! });
  });
  return edges;
}

/** Arma el grafo. Los módulos y sus dependencias quedan en orden alfabético. */
export function buildGraph(edges: readonly Edge[]): Graph {
  const names = new Set<string>();
  for (const edge of edges) names.add(edge.from).add(edge.to);
  const graph: Graph = new Map([...names].sort().map((name) => [name, []]));
  for (const edge of edges) {
    const targets = graph.get(edge.from)!;
    if (!targets.includes(edge.to)) targets.push(edge.to);
  }
  for (const targets of graph.values()) targets.sort();
  return graph;
}

export function edgesOf(graph: Graph): Edge[] {
  return [...graph.entries()].flatMap(([from, targets]) => targets.map((to) => ({ from, to })));
}

/** El mismo grafo sin las flechas indicadas. Falla si alguna no existe. */
export function withoutEdges(graph: Graph, removed: readonly Edge[]): Graph {
  for (const edge of removed) {
    if (!graph.get(edge.from)?.includes(edge.to)) throw new RangeError(`No existe la flecha ${edge.from} -> ${edge.to}`);
  }
  const isRemoved = (from: string, to: string) => removed.some((edge) => edge.from === from && edge.to === to);
  return new Map([...graph.entries()].map(([from, targets]) => [from, targets.filter((to) => !isRemoved(from, to))]));
}

/**
 * Los ciclos elementales (los que no repiten ningún módulo), cada uno una
 * sola vez y escrito a partir de su módulo alfabéticamente menor.
 *
 * Para cada módulo de partida se buscan los caminos que vuelven a él pasando
 * solo por módulos posteriores en orden alfabético: así cada ciclo se
 * encuentra exactamente una vez, desde su módulo menor.
 */
export function elementaryCycles(graph: Graph): string[][] {
  const cycles: string[][] = [];
  for (const start of graph.keys()) {
    const path = [start];
    const walk = (node: string): void => {
      for (const next of graph.get(node)!) {
        if (next === start) cycles.push([...path]);
        else if (next > start && !path.includes(next)) {
          path.push(next);
          walk(next);
          path.pop();
        }
      }
    };
    walk(start);
  }
  return cycles;
}

/** ¿Hay algún ciclo? */
export function hasCycle(graph: Graph): boolean {
  return topologicalOrder(graph) === undefined;
}

/**
 * Un orden en el que cada módulo aparece después de todos aquellos de los que
 * depende (primero lo que no depende de nadie). Existe solo si no hay ciclos:
 * con ciclos devuelve undefined. Entre los módulos que ya se pueden colocar,
 * se elige el primero en orden alfabético.
 */
export function topologicalOrder(graph: Graph): string[] | undefined {
  const pending = new Map([...graph.entries()].map(([name, targets]) => [name, new Set(targets)]));
  const order: string[] = [];
  while (pending.size > 0) {
    const ready = [...pending.keys()].find((name) => pending.get(name)!.size === 0);
    if (ready === undefined) return undefined;
    pending.delete(ready);
    order.push(ready);
    for (const targets of pending.values()) targets.delete(ready);
  }
  return order;
}

/**
 * Los grupos de módulos que están en ciclo entre sí (componentes fuertemente
 * conexas con más de un módulo, o con un módulo que depende de sí mismo): de
 * cada módulo del grupo se llega a todos los demás. Son los "módulos con
 * varios nombres" de la semana 3.
 */
export function tangles(graph: Graph): string[][] {
  const reach = new Map<string, Set<string>>();
  for (const start of graph.keys()) {
    const seen = new Set<string>();
    const stack = [...graph.get(start)!];
    while (stack.length > 0) {
      const node = stack.pop()!;
      if (seen.has(node)) continue;
      seen.add(node);
      stack.push(...graph.get(node)!);
    }
    reach.set(start, seen);
  }
  const groups: string[][] = [];
  const placed = new Set<string>();
  for (const name of graph.keys()) {
    if (placed.has(name) || !reach.get(name)!.has(name)) continue;
    const group = [...graph.keys()].filter((other) => reach.get(name)!.has(other) && reach.get(other)!.has(name));
    group.forEach((member) => placed.add(member));
    groups.push(group);
  }
  return groups;
}

export type Stability = { name: string; dependents: number; dependencies: number; instability: number };

/**
 * Para cada módulo: cuántos dependen de él (Ca), de cuántos depende (Ce) y su
 * inestabilidad I = Ce / (Ca + Ce), como en la semana 3. Un módulo sin
 * ninguna flecha tiene I = 0.
 */
export function stability(graph: Graph): Stability[] {
  return [...graph.entries()].map(([name, targets]) => {
    const dependents = [...graph.values()].filter((others) => others.includes(name)).length;
    const dependencies = targets.length;
    const sum = dependents + dependencies;
    return { name, dependents, dependencies, instability: sum === 0 ? 0 : dependencies / sum };
  });
}

/**
 * Los conjuntos más pequeños de flechas que, quitadas, dejan el grafo sin
 * ciclos. Se prueban todos los conjuntos de 1 flecha, después los de 2, y así:
 * sirve para grafos de examen, no para un sistema real.
 */
export function smallestCuts(graph: Graph): Edge[][] {
  if (!hasCycle(graph)) return [];
  // Solo vale la pena quitar flechas que están en algún ciclo.
  const inCycle = new Map<string, Edge>();
  for (const cycle of elementaryCycles(graph)) {
    cycle.forEach((from, index) => {
      const to = cycle[(index + 1) % cycle.length]!;
      inCycle.set(`${from} -> ${to}`, { from, to });
    });
  }
  const candidates = [...inCycle.values()];
  for (let size = 1; size <= candidates.length; size++) {
    const found = combinations(candidates, size).filter((cut) => !hasCycle(withoutEdges(graph, cut)));
    if (found.length > 0) return found;
  }
  return [];
}

function combinations<T>(items: readonly T[], size: number): T[][] {
  if (size === 0) return [[]];
  return items.flatMap((item, index) => combinations(items.slice(index + 1), size - 1).map((rest) => [item, ...rest]));
}

export const formatEdge = (edge: Edge): string => `${edge.from} -> ${edge.to}`;
export const formatCycle = (cycle: readonly string[]): string => [...cycle, cycle[0]].join(' -> ');
latency.tsDescargar latency.ts
// Percentiles y promedio a partir de una tabla de frecuencias, que es como un
// examen entrega las latencias: "1 700 pedidos tardaron 60 ms, 180 tardaron
// 250 ms...". Son funciones puras: reciben la tabla y devuelven números.
//
// El percentil se calcula por rango más cercano (nearest-rank), el método de
// la semana 2: con los n valores ordenados de menor a mayor, el percentil p
// es el que ocupa la posición ceil(p/100 * n), contando desde 1.

/** Una fila de la tabla: `count` pedidos tardaron `value` milisegundos. */
export type Row = { count: number; value: number };

/** Una fila ya ordenada, con las posiciones que ocupa en la lista completa. */
export type Span = Row & { from: number; to: number };

/**
 * Lee una tabla con una fila por línea: cantidad y valor, separados por
 * espacios. Las líneas vacías y las que empiezan con # se ignoran.
 */
export function parseTable(text: string): Row[] {
  const rows: Row[] = [];
  text.split('\n').forEach((raw, index) => {
    const line = raw.trim();
    if (line === '' || line.startsWith('#')) return;
    const fields = line.split(/\s+/).map(Number);
    const [count, value] = fields;
    if (fields.length !== 2 || count === undefined || value === undefined || !Number.isInteger(count) || count <= 0 || !Number.isFinite(value) || value < 0) {
      throw new SyntaxError(`Línea ${index + 1}: se espera "cantidad valor", con cantidad entera mayor que cero: ${line}`);
    }
    rows.push({ count, value });
  });
  return rows;
}

/** Cuántas mediciones hay en total. */
export function total(rows: readonly Row[]): number {
  return rows.reduce((sum, row) => sum + row.count, 0);
}

/** La posición (desde 1) que ocupa el percentil p en una lista ordenada de n valores. */
export function rank(n: number, p: number): number {
  if (!Number.isInteger(n) || n <= 0) throw new RangeError('No hay percentiles de una lista vacía');
  if (!(p > 0 && p <= 100)) throw new RangeError(`El percentil debe estar en (0, 100]: ${p}`);
  // p/100 * n puede salir con error de redondeo (0.95 * 2000 no es exacto en
  // binario para todos los casos): se redondea a 9 decimales antes del techo.
  return Math.ceil(Number(((p / 100) * n).toFixed(9)));
}

/** Las filas ordenadas por valor, con el rango de posiciones de cada una. */
export function spans(rows: readonly Row[]): Span[] {
  const merged = new Map<number, number>();
  for (const row of rows) merged.set(row.value, (merged.get(row.value) ?? 0) + row.count);
  let position = 0;
  return [...merged.entries()]
    .sort(([a], [b]) => a - b)
    .map(([value, count]) => {
      const span = { count, value, from: position + 1, to: position + count };
      position += count;
      return span;
    });
}

/** El percentil p por rango más cercano: el valor de la fila que contiene esa posición. */
export function percentile(rows: readonly Row[], p: number): number {
  const position = rank(total(rows), p);
  return spans(rows).find((span) => position <= span.to)!.value;
}

/** El promedio aritmético de todas las mediciones. */
export function mean(rows: readonly Row[]): number {
  const n = total(rows);
  if (n === 0) throw new RangeError('No hay promedio de una lista vacía');
  return rows.reduce((sum, row) => sum + row.count * row.value, 0) / n;
}

/** La lista completa, una medición por elemento. Solo para tablas pequeñas y para las pruebas. */
export function expand(rows: readonly Row[]): number[] {
  return rows.flatMap((row) => Array<number>(row.count).fill(row.value));
}
case/atam.mdDescargar case/atam.md
# ATAM reducido de Apachi

Recorrido de los escenarios del caso sobre el diseño del ADR 0001 (los
diagramas están en `context.md` y `containers.md`), con la tabla de la
semana 7.

- Sistema: Apachi
- Presenta: el equipo de Apachi
- Evalúa: la clase, en el repaso de la semana 8

## Objetivos del negocio

- Que ninguna agencia deje de recibir encomiendas, tampoco en campaña.
- Que el destinatario sepa dónde está su encomienda sin llamar a la agencia.
- Que una encomienda registrada no se pierda ni se entregue a otra persona.

## Enfoques de arquitectura

| Id | Enfoque | Dónde se ve |
|---|---|---|
| A1 | Cada agencia registra en un nodo local con su propio almacén | Contenedores: Nodo de agencia y Almacén de la agencia |
| A2 | El nodo envía a la central lo pendiente, con reintentos, cuando hay enlace | Contenedores: relación del Nodo de agencia con la API central |
| A3 | El comprobante y el SMS salen después, desde una tabla de pendientes | Contenedores: Trabajador de efectos |
| A4 | El código de seguimiento lleva el prefijo de la agencia y una parte aleatoria | ADR 0001, consecuencias |
| A5 | El nodo calcula el precio con una copia local de las tarifas | Contenedores: Almacén de la agencia |

## Escenarios

| Id | Escenario | Atributo | Origen |
|---|---|---|---|
| E1 | Sin enlace 2 h en campaña: el mostrador sigue registrando, 0 encomiendas perdidas, todo consultable en 10 min o menos al volver | disponibilidad | utility tree (A, A) |
| E2 | 40 consultas de seguimiento por segundo durante 2 h: p95 menor que 500 ms, errores menores que 0,5 % | rendimiento | utility tree (A, M) |
| E4 | 10 000 códigos probados en 1 h: 0 datos personales devueltos, alerta en 5 min o menos | seguridad | utility tree (A, M) |
| E5 | Una versión nueva del nodo se instala agencia por agencia durante 1 semana: la central rechaza 0 encomiendas de las agencias que aún tienen la versión anterior | modificabilidad | lluvia de ideas (4 votos) |

## Hallazgos

| Id | Tipo | Escenarios | Enfoques | Decisión | Atributos | Razonamiento |
|---|---|---|---|---|---|---|
| N1 | no riesgo | E1 | A1 | El nodo guarda la encomienda en su almacén antes de responder al mostrador | disponibilidad | Registrar no usa el enlace, la API central ni a los proveedores, así que la caída de 2 h no lo toca. Vale mientras la computadora de la agencia funcione |
| R1 | riesgo | E1 | A1, A2 | Hasta que se envía, la encomienda existe en un solo disco de la agencia | disponibilidad | Si el disco se daña durante las 2 h sin enlace, se pierden unas 80 encomiendas (40 por hora), y la medida pide 0 |
| S1 | punto de sensibilidad | E1 | A2 | Cada cuánto intenta el nodo enviar lo pendiente | disponibilidad | Al volver el enlace hay unas 80 encomiendas por enviar y 10 min para que se puedan consultar: si el nodo reintenta cada 15 min, la medida no se cumple aunque todo lo demás funcione |
| R2 | riesgo | E1 | A2 | El nodo reenvía lo que no recibió respuesta, y nadie decidió todavía cómo reconoce la central un envío repetido | disponibilidad | Un envío que llegó y cuya respuesta se perdió se repite: sin esa decisión, la misma encomienda queda registrada dos veces, con dos comprobantes |
| R3 | riesgo | E5 | A2 | Lo que el nodo envía a la central no lleva versión de formato | modificabilidad | Con 38 instalaciones que se actualizan una por una, durante días llegan envíos con dos formatos; si la central solo entiende el nuevo, rechaza los de las agencias que faltan |
| T1 | punto de trade-off | E1, E4 | A1, A5 | Qué datos se guardan en la agencia y por cuánto tiempo | disponibilidad, seguridad | Cuanto más guarda el nodo (tarifas, destinatarios, historial), más puede hacer sin enlace, y más datos personales quedan en 38 computadoras de mostrador |
| T2 | punto de trade-off | E1, E2 | A2 | La central recibe las encomiendas después de registradas, no al registrarlas | disponibilidad, rendimiento | Es lo que permite registrar sin enlace, y hace que una consulta de seguimiento por una encomienda recién registrada no encuentre nada. Los pedidos que no encuentran su código son otra población en la tabla de latencias |
| N2 | no riesgo | E4 | A4 | El código de seguimiento tiene una parte aleatoria y no sale de una secuencia | seguridad | Con códigos consecutivos, quien tiene uno acierta el siguiente al primer intento. Con una parte aleatoria de 8 caracteres entre 32 símbolos hay más de un billón de combinaciones por agencia, y 10 000 intentos no alcanzan |

## Temas de riesgo

| Tema | Riesgos | Objetivo del negocio que amenaza |
|---|---|---|
| El contrato entre el nodo y la central está sin decidir: qué pasa con un envío repetido y con un formato anterior | R2, R3 | Que una encomienda registrada no se pierda ni se entregue a otra persona |
case/containers.mdDescargar case/containers.md
# Apachi: diagrama de contenedores

- Nivel: contenedores
- Sistema: Apachi

El diseño que queda después del ADR-0001: cada agencia registra en su propio
nodo y la central se entera después.

## Elementos

| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Encargado de agencia | persona | Atiende el mostrador: registra encomiendas, entrega la guía y entrega la encomienda a su destinatario | — |
| Destinatario | persona | Consulta el estado de su encomienda con el código de seguimiento y la recoge en la agencia de destino | — |
| Aplicación de mostrador | contenedor | Las pantallas de registro y de entrega; corre en el navegador de la computadora de la agencia | TypeScript y HTML, sin framework |
| Nodo de agencia | contenedor | Registra las encomiendas de su agencia, calcula el precio con su copia de las tarifas, genera el código de seguimiento y envía a la central lo que tiene pendiente | Node.js 26, node:http, en la computadora de la agencia |
| Almacén de la agencia | almacén de datos | Encomiendas registradas en la agencia, cuáles falta enviar a la central y la copia local de las tarifas | SQLite, en el disco cifrado de la computadora de la agencia |
| API central | contenedor | Recibe las encomiendas de los nodos, responde el seguimiento, publica las tarifas y anota los comprobantes y avisos por enviar | Node.js 26, node:http, en la nube |
| Página de seguimiento | contenedor | La página donde el destinatario escribe su código y ve el recorrido; corre en el navegador de su celular | TypeScript y HTML, sin framework |
| Trabajador de efectos | contenedor | Programa que toma los comprobantes y los avisos pendientes, los envía y reintenta los que fallaron | Node.js 26, proceso aparte de la API |
| Base de datos central | almacén de datos | Encomiendas de todas las agencias, su recorrido, las tarifas y los comprobantes y avisos pendientes | PostgreSQL 18 |
| Proveedor de facturación | sistema externo | Emite el comprobante electrónico de cada encomienda y devuelve su número | API REST del proveedor contratado |
| Proveedor de SMS | sistema externo | Entrega mensajes de texto a los celulares de los destinatarios | API REST del proveedor |

## Relaciones

| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Encargado de agencia | Aplicación de mostrador | Registra encomiendas y entregas | Navegador web |
| Aplicación de mostrador | Nodo de agencia | Pide registrar una encomienda, cotizar un precio o anotar una entrega | HTTP, JSON, en la red de la agencia |
| Nodo de agencia | Almacén de la agencia | Guarda cada encomienda antes de responder al mostrador y marca las ya enviadas | SQL sobre un archivo local |
| Nodo de agencia | API central | Envía las encomiendas y entregas pendientes, y pide las tarifas vigentes | HTTPS, JSON, cuando hay enlace |
| Destinatario | Página de seguimiento | Consulta el estado de su encomienda con el código | Navegador web |
| Página de seguimiento | API central | Pide el recorrido de una encomienda por su código | HTTPS, JSON |
| API central | Base de datos central | Guarda encomiendas y recorridos, y consulta el seguimiento | Protocolo de PostgreSQL sobre TCP (SQL) |
| Trabajador de efectos | Base de datos central | Toma los comprobantes y avisos pendientes y anota los enviados | Protocolo de PostgreSQL sobre TCP (SQL) |
| Trabajador de efectos | Proveedor de facturación | Envía los datos de cada encomienda para emitir su comprobante | HTTPS, JSON |
| Trabajador de efectos | Proveedor de SMS | Envía el código de seguimiento y el aviso de llegada | HTTPS, JSON |
| Proveedor de SMS | Destinatario | Entrega el código de seguimiento y el aviso de llegada | SMS |
case/context.mdDescargar case/context.md
# Apachi: diagrama de contexto

- Nivel: contexto
- Sistema: Apachi

Apachi registra encomiendas en las agencias de una empresa de transporte y
deja que el destinatario siga la suya. Depende de dos sistemas que no son
suyos, y con los dos la relación es de envío: ninguno está en el camino del
registro.

## Elementos

| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Encargado de agencia | persona | Atiende el mostrador: registra encomiendas, entrega la guía y entrega la encomienda a su destinatario | — |
| Destinatario | persona | Consulta el estado de su encomienda con el código de seguimiento y la recoge en la agencia de destino | — |
| Apachi | sistema | Registro, seguimiento y entrega de encomiendas en las 38 agencias, con su comprobante y sus avisos | Nodos de Node.js en las agencias y una API central con PostgreSQL |
| Proveedor de facturación | sistema externo | Emite el comprobante electrónico de cada encomienda y devuelve su número | API REST del proveedor contratado |
| Proveedor de SMS | sistema externo | Entrega mensajes de texto a los celulares de los destinatarios | API REST del proveedor |

## Relaciones

| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Encargado de agencia | Apachi | Registra encomiendas y entregas | Navegador web, en la red de la agencia |
| Destinatario | Apachi | Consulta el estado de su encomienda con el código | HTTPS, desde el navegador |
| Apachi | Proveedor de facturación | Envía los datos de cada encomienda para emitir su comprobante | HTTPS, JSON |
| Apachi | Proveedor de SMS | Envía el código de seguimiento y el aviso de llegada | HTTPS, JSON |
| Proveedor de SMS | Destinatario | Entrega el código de seguimiento y el aviso de llegada | SMS |
case/requirements.mdDescargar case/requirements.md
# Apachi: lo que pidió la empresa

Apachi (del quechua *apachiy*, enviar) es el caso de la semana 8: el sistema
de encomiendas de una empresa de transporte interprovincial con 38 agencias.
No existe: sirve para practicar con un sistema que no es Tinkuy. La lista es
la que salió de las reuniones con la empresa, tal como la dijeron.

1. El encargado de la agencia registra una encomienda (remitente,
   destinatario, peso, valor declarado, destino); el sistema calcula el precio
   y entrega una guía con un código de seguimiento.
2. El destinatario consulta el estado de su encomienda con el código, desde
   su celular, sin crear una cuenta.
3. El destinatario recibe un SMS con el código cuando la encomienda se
   registra, y otro cuando llega a la agencia de destino.
4. Para recoger, el destinatario muestra su DNI; el sistema guarda quién
   entregó y a quién.
5. El sistema tiene que ser robusto y fácil de usar.
6. En la campaña de diciembre se registran unas 9 000 encomiendas al día (un
   día normal son 1 500), y por las tardes llegan unas 40 consultas de
   seguimiento por segundo.
7. Doce agencias de la sierra y de la selva pierden la conexión a internet
   varias veces al mes, a veces por horas. El mostrador no puede dejar de
   recibir encomiendas.
8. Las tarifas cambian por ruta y por temporada. Gerencia comercial las
   cambia unas seis veces al año, y hoy cada cambio demora dos semanas.
9. Cada encomienda lleva un comprobante electrónico. Lo emite un proveedor de
   facturación con el que la empresa ya tiene contrato.
10. El sistema corre en la nube de un proveedor que la empresa ya contrató.
    El equipo son cinco personas, que conocen TypeScript y PostgreSQL.
11. Una encomienda registrada no se puede perder, ni entregarse a quien no es
    su destinatario.

Después de preguntar "¿y si falla?" por los requisitos 3 y 9, la empresa
respondió: si el proveedor de SMS o el de facturación no responden, el
mostrador sigue recibiendo; el SMS y el comprobante pueden llegar después.
(Es un supuesto del caso. En un sistema real, cuándo puede emitirse un
comprobante lo dice la norma tributaria, y hay que consultarla.)
case/scenarios.mdDescargar case/scenarios.md
# Escenarios de calidad de Apachi

Los cuatro escenarios del caso de la semana 8, con el template de la semana 2
(`../week-02/scenario-template.md`). Son las hojas de `utility-tree.md`.

## E1. Una agencia se queda sin enlace

- **Atributo de calidad:** disponibilidad
- **Fuente del estímulo:** el enlace a internet de una agencia de la sierra
- **Estímulo:** deja de funcionar durante 2 horas
- **Artefacto:** el registro de encomiendas en el mostrador de esa agencia
- **Entorno:** campaña de diciembre, con unas 40 encomiendas por hora en esa agencia
- **Respuesta:** el mostrador sigue registrando y entrega a cada remitente su guía con el código de seguimiento; cuando el enlace vuelve, las encomiendas registradas sin enlace aparecen en el seguimiento
- **Medida de la respuesta:** 0 encomiendas perdidas, y el 100 % de las registradas sin enlace se puede consultar en 10 minutos o menos desde que el enlace vuelve

## E2. Consultas de seguimiento en la campaña

- **Atributo de calidad:** rendimiento
- **Fuente del estímulo:** destinatarios, desde su celular
- **Estímulo:** hacen 40 consultas de seguimiento por segundo durante 2 horas
- **Artefacto:** el endpoint de seguimiento (`GET /tracking/:code`)
- **Entorno:** una tarde de la campaña de diciembre, con 90 000 encomiendas en tránsito
- **Respuesta:** el sistema devuelve el estado de la encomienda y su recorrido
- **Medida de la respuesta:** latencia p95 menor que 500 ms y menos de 0,5 % de errores, medidos desde fuera del centro de datos

## E3. Una tarifa nueva para una ruta

- **Atributo de calidad:** modificabilidad
- **Fuente del estímulo:** gerencia comercial
- **Estímulo:** pide una tarifa nueva para una ruta y una temporada
- **Artefacto:** el módulo de tarifas
- **Entorno:** el sistema en operación, fuera de campaña
- **Respuesta:** una persona del equipo hace el cambio, lo prueba y lo despliega sin detener el registro de encomiendas
- **Medida de la respuesta:** 1 día-persona o menos, 1 módulo modificado y 0 minutos de interrupción del registro

## E4. Alguien recorre códigos de seguimiento

- **Atributo de calidad:** seguridad
- **Fuente del estímulo:** una persona ajena a la empresa, con un código de seguimiento válido
- **Estímulo:** prueba 10 000 códigos parecidos al suyo en una hora, para ver encomiendas de otros
- **Artefacto:** el endpoint de seguimiento (`GET /tracking/:code`)
- **Entorno:** operación normal
- **Respuesta:** el sistema no entrega datos de otras encomiendas, limita los pedidos de ese origen y avisa al equipo
- **Medida de la respuesta:** 0 nombres, teléfonos o direcciones devueltos, menos de 1 código ajeno acertado por cada 10 000 intentos, y una alerta en 5 minutos o menos
case/utility-tree.mdDescargar case/utility-tree.md
# Utility tree de Apachi

Los escenarios están completos, con sus seis partes, en `scenarios.md`. Cada
hoja lleva dos notas, Alta (A), Media (M) o Baja (B): valor para el negocio y
dificultad técnica con el diseño actual (un monolito en la nube, al que las
agencias entran con el navegador).

| Atributo | Refinamiento | Escenario (resumen) | Negocio | Técnica |
|---|---|---|---|---|
| Disponibilidad | Falla del enlace de una agencia | E1. Sin enlace 2 h: el mostrador sigue registrando, 0 encomiendas perdidas, todo consultable en 10 min o menos al volver | A | A |
| Rendimiento | Latencia del seguimiento | E2. 40 consultas por segundo durante 2 h: p95 < 500 ms, errores < 0,5 % | A | M |
| Modificabilidad | Cambios de tarifa | E3. Tarifa nueva para una ruta: 1 día-persona o menos, 1 módulo, 0 min de interrupción | M | B |
| Seguridad | Confidencialidad | E4. 10 000 códigos probados en 1 h: 0 datos personales devueltos, alerta en 5 min o menos | A | M |

- Utilidad
  - Disponibilidad
    - Falla del enlace de una agencia
      - **E1 (A, A)**
  - Rendimiento
    - Latencia del seguimiento
      - E2 (A, M)
  - Modificabilidad
    - Cambios de tarifa
      - E3 (M, B)
  - Seguridad
    - Confidencialidad
      - E4 (A, M)
coupling/quote.tsDescargar coupling/quote.ts
// El precio de una encomienda en Apachi, escrito dos veces. La cuenta es la
// misma; cambia cuánto tiene que saber quien llama para no equivocarse.

const BASE_CENTS = 800;
const PER_KG_CENTS = 150;
const EXPRESS_FACTOR = 1.5;

// --- Primera versión. Quien llama tiene que saber tres cosas que el tipo no
// dice: el orden de los dos primeros argumentos (connascence de posición), que
// el valor declarado va en soles y no en céntimos, y que 1 es el servicio
// normal y 2 el express (connascence de significado, las dos).
export function quoteByPosition(weightKg: number, declaredValue: number, service: number): number {
  const insuranceCents = Math.round(declaredValue * 100 * 0.01);
  const cents = BASE_CENTS + Math.ceil(weightKg) * PER_KG_CENTS + insuranceCents;
  return service === 2 ? Math.round(cents * EXPRESS_FACTOR) : cents;
}

// --- Segunda versión. Los campos tienen nombre, la unidad está en el nombre y
// el servicio es una unión de literales: lo que queda es connascence de
// nombre, la más débil.
export type Service = 'standard' | 'express';

export type Parcel = { weightKg: number; declaredValueCents: number; service: Service };

export function quoteCents(parcel: Parcel): number {
  const insuranceCents = Math.round(parcel.declaredValueCents * 0.01);
  const cents = BASE_CENTS + Math.ceil(parcel.weightKg) * PER_KG_CENTS + insuranceCents;
  return parcel.service === 'express' ? Math.round(cents * EXPRESS_FACTOR) : cents;
}
data/modules.txtDescargar data/modules.txt
# Apachi: dependencias entre los módulos del monolito. "a -> b" quiere decir
# que a importa algo de b.
shipments -> agencies
shipments -> tariffs
shipments -> billing
shipments -> tracking
billing -> shipments
billing -> tariffs
tariffs -> agencies
tracking -> agencies
tracking -> notifications
notifications -> shipments
data/register-agency-node.txtDescargar data/register-agency-node.txt
# Alternativa 3: el registro se hace en un nodo local de la agencia y se
# sincroniza después. Registrar necesita solo la computadora de la agencia.
nodo de la agencia: 99.8
data/register-backup-link.txtDescargar data/register-backup-link.txt
data/register-central.txtDescargar data/register-central.txt
# Apachi, diseño actual: lo que necesita el mostrador de una agencia de la
# sierra para registrar una encomienda. Todo se hace dentro de la petición.
enlace de la agencia: 99.2
API central: 99.95
PostgreSQL: 99.95
proveedor de facturación: 99.5
proveedor de SMS: 99.9
data/register-deferred-effects.txtDescargar data/register-deferred-effects.txt
# Alternativa 1: el comprobante y el SMS salen después, desde una tabla de
# pendientes. El registro ya no los necesita para completarse.
enlace de la agencia: 99.2
API central: 99.95
PostgreSQL: 99.95
data/tracking-api-1.txtDescargar data/tracking-api-1.txt
# La misma prueba, solo los pedidos que atendió la instancia api-1.
1900 60
data/tracking-api-2.txtDescargar data/tracking-api-2.txt
# La misma prueba, solo los pedidos que atendió la instancia api-2.
100 900
data/tracking-latencies.txtDescargar data/tracking-latencies.txt
# Apachi: tiempo de respuesta de GET /tracking/:code en una prueba de carga
# con el tráfico de la campaña de diciembre. Cada línea: cuántos pedidos
# tardaron cuántos milisegundos.
1700 60
180 250
90 900
30 6000
case/adr/0001-registro-local-en-la-agencia.mdDescargar case/adr/0001-registro-local-en-la-agencia.md
# ADR 0001: Las agencias registran encomiendas en un nodo local

## Contexto

Doce de las 38 agencias pierden el enlace a internet varias veces al mes, a
veces por horas. Hoy el mostrador es una página que habla con un monolito en
la nube: registrar una encomienda necesita, en serie, el enlace de la agencia
(99,2 % en esas doce), la API, PostgreSQL, el proveedor de facturación y el
de SMS. La cuenta da 98,5 %, y sin enlace no se registra nada: el encargado
llena la guía en papel y la digita después.

La empresa aceptó que el comprobante y el SMS lleguen después del registro.
El equipo son cinco personas y la nube ya está contratada.

**Escenario:** E1, el único (A, A) del utility tree: con el enlace de una agencia caído 2 horas en plena campaña, el mostrador sigue registrando, se pierden 0 encomiendas y el 100 % se puede consultar en 10 minutos o menos desde que el enlace vuelve.

## Alternativas consideradas

### A. No cambiar el diseño

- **Gana:** no hay nada que construir ni que operar; el seguimiento muestra siempre lo mismo que la base de datos central.
- **Cuesta:** sin enlace, la encomienda no tiene código de seguimiento hasta que alguien la digita, y en campaña la digitación se atrasa.
- **Por qué no:** no cumple E1: durante las 2 horas no se registra nada en el sistema.

### B. Efectos diferidos y un segundo enlace

- **Gana:** el comprobante y el SMS salen de una tabla de pendientes y dejan de estar en el camino; con un enlace 4G de respaldo de 97 %, registrar sube a 99,88 % si las caídas de los dos enlaces son independientes. El diseño sigue siendo un solo despliegue.
- **Cuesta:** un contrato mensual por agencia, y un proceso más (el que envía los pendientes).
- **Por qué no:** en esas agencias los dos enlaces dependen de la misma energía y, a veces, de la misma torre, así que sus caídas no son independientes. Mejora el promedio y no cumple E1, que describe justamente las 2 horas en que no hay ninguno.

### C. Un nodo local en cada agencia

- **Gana:** registrar necesita solo la computadora de la agencia; el enlace, la API central y los dos proveedores salen del camino del mostrador.
- **Cuesta:** 38 instalaciones que operar, consistencia eventual entre la agencia y la central, y datos personales fuera del centro de datos.

## Decisión

- **Alternativa elegida:** C

Vamos a instalar en cada agencia un nodo: un programa en la computadora del
mostrador, con su propio almacén en disco. El nodo registra la encomienda,
calcula el precio con su copia de las tarifas, genera el código de
seguimiento y responde al mostrador sin hablar con la central. Lo registrado
queda marcado como pendiente y el nodo lo envía a la API central cuando hay
enlace, las veces que haga falta. La central emite el comprobante y el SMS
después, desde su tabla de pendientes. Es la única alternativa en la que E1
no depende del enlace. Habría que revisarla si las doce agencias consiguen
un enlace que no se caiga por horas.

## Estado

Aceptado

## Consecuencias

- **Buena:** con el enlace caído, el mostrador sigue registrando y entrega la guía con su código. E1 se puede cumplir.
- **Buena:** un proveedor externo que no responde ya no detiene a ninguna agencia.
- **Mala:** el seguimiento es eventualmente consistente: una encomienda registrada sin enlace no existe para el destinatario hasta que el nodo la envía.
- **Mala:** un nodo sin enlace cobra con la última tarifa que recibió. Se acepta que vale el precio de la guía, y un cambio de tarifa se publica con días de anticipación.
- **Mala:** el nodo puede enviar la misma encomienda dos veces (envía, no recibe respuesta, reintenta). La central tiene que reconocerla por su código y no registrarla de nuevo.
- **Mala:** hasta que se envía, una encomienda existe en un solo disco. Si ese disco se daña, se pierde: es un riesgo abierto frente a las 0 encomiendas perdidas de E1.
- **Mala:** hay datos personales en 38 computadoras de mostrador y 38 instalaciones que actualizar. Durante una actualización conviven dos versiones del nodo, y la API central tiene que aceptar las dos.
- **Neutra:** el código de seguimiento ya no sale de una secuencia de la base de datos central: lleva el prefijo de la agencia y una parte aleatoria.
deps/src/main.tsDescargar deps/src/main.ts
// Composition root: el único lugar que conoce a los dos módulos y los conecta.
import { createBilling } from './billing/index.ts';
import { createCounter } from './shipments/index.ts';

const billing = createBilling('B001');
let sequence = 0;
const counter = createCounter({ receipts: billing, nextCode: () => `TAR-${String(++sequence).padStart(6, '0')}` });

const { shipment, receiptNumber } = await counter.register({
  originAgency: 'Tarma',
  destinationAgency: 'Lima',
  weightKg: 3,
  priceCents: 1450,
  recipientPhone: '999000111',
});
console.log(`Encomienda ${shipment.code} de ${shipment.originAgency} a ${shipment.destinationAgency}`);
console.log(`Comprobante ${receiptNumber}, IGV ${billing.issued()[0]!.taxCents} céntimos`);
deps/src/billing/index.tsDescargar deps/src/billing/index.ts
// Interfaz pública del módulo billing.
export { createBilling } from './receipts.ts';
export type { Billing, Receipt } from './receipts.ts';
deps/src/billing/receipts.tsDescargar deps/src/billing/receipts.ts
import type { ReceiptIssuer, Shipment } from '../shipments/index.ts';

export type Receipt = { number: string; shipmentCode: string; totalCents: number; taxCents: number };

// El precio de la encomienda ya incluye el IGV (18 %): el impuesto es
// 18/118 del total.
const TAX_PERCENT = 18;

export type Billing = ReceiptIssuer & { issued(): readonly Receipt[] };

// billing sabe emitir comprobantes y se adapta a la interfaz que declaró
// shipments. Aquí los guarda en memoria; en el sistema real, este es el único
// módulo que hablaría con el proveedor de facturación.
export function createBilling(series: string): Billing {
  const receipts: Receipt[] = [];
  return {
    async issue(shipment: Shipment) {
      const number = `${series}-${String(receipts.length + 1).padStart(8, '0')}`;
      const taxCents = Math.round((shipment.priceCents * TAX_PERCENT) / (100 + TAX_PERCENT));
      receipts.push({ number, shipmentCode: shipment.code, totalCents: shipment.priceCents, taxCents });
      return number;
    },
    issued: () => receipts,
  };
}
deps/src/shipments/counter.tsDescargar deps/src/shipments/counter.ts
import type { ReceiptIssuer } from './ports.ts';
import type { NewShipment, Shipment } from './types.ts';

export type Registration = { shipment: Shipment; receiptNumber: string };

export type Counter = { register(input: NewShipment): Promise<Registration> };

// El mostrador recibe desde afuera lo que necesita: quién emite el
// comprobante y cómo se genera el código de seguimiento. No importa a billing.
export function createCounter(deps: { receipts: ReceiptIssuer; nextCode: () => string }): Counter {
  return {
    async register(input) {
      if (!(input.weightKg > 0)) throw new RangeError('El peso debe ser mayor que cero');
      const shipment: Shipment = { ...input, code: deps.nextCode() };
      const receiptNumber = await deps.receipts.issue(shipment);
      return { shipment, receiptNumber };
    },
  };
}
deps/src/shipments/index.tsDescargar deps/src/shipments/index.ts
// Interfaz pública del módulo shipments.
export { createCounter } from './counter.ts';
export type { Counter, Registration } from './counter.ts';
export type { ReceiptIssuer } from './ports.ts';
export type { NewShipment, Shipment } from './types.ts';
deps/src/shipments/ports.tsDescargar deps/src/shipments/ports.ts
import type { Shipment } from './types.ts';

// Lo que el registro de encomiendas necesita de quien emite comprobantes. La
// interfaz es de shipments, que es quien la usa: dice "emite el comprobante
// de esta encomienda y dame su número", y no menciona series, impuestos ni al
// proveedor de facturación.
export interface ReceiptIssuer {
  issue(shipment: Shipment): Promise<string>;
}
deps/src/shipments/types.tsDescargar deps/src/shipments/types.ts
// Una encomienda ya registrada en el mostrador.
export type Shipment = {
  code: string;
  originAgency: string;
  destinationAgency: string;
  weightKg: number;
  priceCents: number;
  recipientPhone: string;
};

export type NewShipment = Omit<Shipment, 'code'>;

Errores

Ejemplos con errores a propósito: no compilan, fallan o dan un resultado incorrecto. Los apuntes explican cada uno.

errors/tsconfig.jsonDescargar errors/tsconfig.json
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["deps"]
}
errors/vague-scenarios.mdDescargar errors/vague-scenarios.md
# Escenarios de Apachi mal escritos

Dos escenarios como salen en un primer intento. `make errors` los pasa por el
revisor de la semana 2, que dice qué le falta a cada uno. En el apunte están
corregidos (son E2 y E4 de `case/scenarios.md`).

## El seguimiento debe ser rápido

- **Atributo de calidad:** rendimiento
- **Fuente del estímulo:** los usuarios
- **Estímulo:** consultan sus encomiendas
- **Artefacto:** el sistema
- **Respuesta:** el sistema responde
- **Medida de la respuesta:** siempre en un tiempo razonable

## Nadie ve encomiendas ajenas

- **Atributo de calidad:** seguridad
- **Fuente del estímulo:** un atacante
- **Estímulo:** intenta ver encomiendas de otros
- **Artefacto:** el seguimiento
- **Entorno:** operación normal
- **Respuesta:** el sistema lo impide
- **Medida de la respuesta:** el sistema es seguro
errors/cycle/src/main.tsDescargar errors/cycle/src/main.ts
// Versión con el ciclo: no hay nada que conectar, cada módulo ya importó al otro.
import { issued } from './billing/index.ts';
import { createCounter } from './shipments/index.ts';

let sequence = 0;
const counter = createCounter({ nextCode: () => `TAR-${String(++sequence).padStart(6, '0')}` });

const { shipment, receiptNumber } = await counter.register({
  originAgency: 'Tarma',
  destinationAgency: 'Lima',
  weightKg: 3,
  priceCents: 1450,
  recipientPhone: '999000111',
});
console.log(`Encomienda ${shipment.code} de ${shipment.originAgency} a ${shipment.destinationAgency}`);
console.log(`Comprobante ${receiptNumber}, IGV ${issued()[0]!.taxCents} céntimos`);
errors/cycle/src/billing/index.tsDescargar errors/cycle/src/billing/index.ts
// Interfaz pública del módulo billing (versión con el ciclo).
export { issueReceipt, issued } from './receipts.ts';
export type { Receipt } from './receipts.ts';
errors/cycle/src/billing/receipts.tsDescargar errors/cycle/src/billing/receipts.ts
import type { Shipment } from '../shipments/index.ts';

export type Receipt = { number: string; shipmentCode: string; totalCents: number; taxCents: number };

const TAX_PERCENT = 18;
const SERIES = 'B001';
const receipts: Receipt[] = [];

// Una función suelta, con el estado en el módulo: quien la quiera usar tiene
// que importarla, y para probar el mostrador hay que cargar la facturación.
export async function issueReceipt(shipment: Shipment): Promise<string> {
  const number = `${SERIES}-${String(receipts.length + 1).padStart(8, '0')}`;
  const taxCents = Math.round((shipment.priceCents * TAX_PERCENT) / (100 + TAX_PERCENT));
  receipts.push({ number, shipmentCode: shipment.code, totalCents: shipment.priceCents, taxCents });
  return number;
}

export const issued = (): readonly Receipt[] => receipts;
errors/cycle/src/shipments/counter.tsDescargar errors/cycle/src/shipments/counter.ts
// Versión con el ciclo: el mostrador importa a billing para emitir el
// comprobante, y billing importa a shipments para saber qué es una encomienda.
import { issueReceipt } from '../billing/index.ts';
import type { NewShipment, Shipment } from './types.ts';

export type Registration = { shipment: Shipment; receiptNumber: string };

export type Counter = { register(input: NewShipment): Promise<Registration> };

export function createCounter(deps: { nextCode: () => string }): Counter {
  return {
    async register(input) {
      if (!(input.weightKg > 0)) throw new RangeError('El peso debe ser mayor que cero');
      const shipment: Shipment = { ...input, code: deps.nextCode() };
      const receiptNumber = await issueReceipt(shipment);
      return { shipment, receiptNumber };
    },
  };
}

Pruebas

Comprueban lo que afirman los apuntes; se ejecutan con make test.

availability.test.tsDescargar availability.test.ts
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { test } from 'node:test';
import * as week2 from '../week-02/stats.ts';
import { chainAvailability, downtimeHoursPerYear, downtimeMinutesPerMonth, inParallel, inSeries, parseChain, stageAvailability } from './availability.ts';

const chain = (name: string) => parseChain(readFileSync(new URL(`data/${name}`, import.meta.url), 'utf8'));
const percent = (fraction: number, digits = 2) => Number((fraction * 100).toFixed(digits));

test('en serie se multiplican: tres servicios de 99,9 % dan 99,7 %', () => {
  assert.equal(percent(inSeries([0.999, 0.999, 0.999]), 1), 99.7);
});

test('en paralelo falla solo si fallan todas: dos copias de 99 % dan 99,99 %', () => {
  assert.equal(percent(inParallel([0.99, 0.99])), 99.99);
});

test('el conjunto en serie es peor que su peor parte, y una copia más nunca empeora una etapa', () => {
  const parts = [0.992, 0.9995, 0.9995, 0.995, 0.999];
  assert.equal(inSeries(parts) < Math.min(...parts), true);
  assert.equal(inParallel([0.992, 0.97]) > 0.992, true);
});

test('Apachi hoy: registrar en una agencia de la sierra tiene 98,5 % (unas 131 horas al año)', () => {
  const whole = chainAvailability(chain('register-central.txt'));
  assert.equal(percent(whole, 1), 98.5);
  assert.equal(Math.round(downtimeHoursPerYear(whole)), 131);
  assert.equal(Math.round(downtimeMinutesPerMonth(whole)), 645);
});

test('sacar el comprobante y el SMS del camino sube a 99,1 %, y no puede pasar del 99,2 % del enlace', () => {
  const whole = chainAvailability(chain('register-deferred-effects.txt'));
  assert.equal(percent(whole, 1), 99.1);
  assert.equal(whole < 0.992, true);
});

test('con un segundo enlace de 97 %, el enlace sube a 99,976 % y el registro a 99,88 %, si las caídas son independientes', () => {
  const stages = chain('register-backup-link.txt');
  assert.equal(percent(stageAvailability(stages[0]!), 3), 99.976);
  assert.equal(percent(chainAvailability(stages)), 99.88);
});

test('con el nodo local, registrar depende de una sola pieza', () => {
  const stages = chain('register-agency-node.txt');
  assert.equal(stages.length, 1);
  assert.equal(percent(chainAvailability(stages), 1), 99.8);
});

test('da lo mismo que stats.ts de la semana 2', () => {
  const parts = [0.992, 0.9995, 0.9995, 0.995, 0.999];
  assert.equal(inSeries(parts), week2.availabilityInSeries(parts));
  assert.equal(inParallel([0.992, 0.97]), week2.availabilityInParallel([0.992, 0.97]));
  assert.equal(downtimeHoursPerYear(0.999), week2.downtimeHoursPerYear(0.999));
});

test('la cadena acepta coma decimal y rechaza lo que no es un porcentaje', () => {
  assert.deepEqual(parseChain('enlace: 99,2 | 97\n'), [{ name: 'enlace', copies: [0.992, 0.97] }]);
  assert.throws(() => parseChain('enlace: mucho\n'), /Línea 1/);
  assert.throws(() => parseChain('enlace: 120\n'), /Línea 1/);
  assert.throws(() => parseChain('# nada\n'), SyntaxError);
});
case.test.tsDescargar case.test.ts
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { test } from 'node:test';
import { checkDiagram, checkSet } from '../week-01/c4.ts';
import { checkMarkdown } from '../week-02/scenario-check.ts';

// Los documentos del caso pasan los mismos revisores que usaron en las
// semanas 1 y 2 para sus propios escenarios y diagramas. (El ADR y la tabla
// del ATAM se revisan con los de la semana 7: `make case`.)

const read = (path: string) => readFileSync(new URL(path, import.meta.url), 'utf8');

test('los cuatro escenarios de Apachi tienen sus seis partes y una medida con número', () => {
  const report = checkMarkdown(read('case/scenarios.md'));
  assert.equal(report.scenarios.length, 4);
  assert.equal(report.ok, true);
});

test('los dos escenarios de errors/ no pasan: sin entorno, y con una medida que no se puede comprobar', () => {
  const report = checkMarkdown(read('errors/vague-scenarios.md'));
  assert.equal(report.ok, false);
  const [fast, safe] = report.scenarios.map((entry) => entry.problems.map((problem) => `${problem.part}: ${problem.message}`));
  assert.deepEqual(fast, ['environment: falta', 'measure: no tiene ningún número: ¿cómo se comprueba?', 'measure: "siempre" no se puede comprobar: escriban el número']);
  assert.deepEqual(safe, ['measure: no tiene ningún número: ¿cómo se comprueba?']);
});

test('los diagramas de contexto y de contenedores están completos y son coherentes entre sí', () => {
  const files = ['case/context.md', 'case/containers.md'];
  const checked = files.map((file) => ({ file, ...checkDiagram(read(file)) }));
  for (const { file, issues } of checked) assert.deepEqual(issues, [], file);
  assert.deepEqual(checkSet(checked.map(({ file, diagram }) => ({ file, diagram }))), []);
});

test('en el diseño decidido, lo único que habla con un proveedor externo es el trabajador de efectos', () => {
  const { diagram } = checkDiagram(read('case/containers.md'));
  const external = new Set(diagram.elements.filter((element) => element.kind === 'sistema externo').map((element) => element.name));
  const callers = diagram.relationships.filter((relationship) => external.has(relationship.to)).map((relationship) => relationship.from);
  assert.deepEqual([...new Set(callers)], ['Trabajador de efectos']);
});

test('el ADR tiene las secciones del formato de la semana 7, tres alternativas y una elegida', () => {
  const adr = read('case/adr/0001-registro-local-en-la-agencia.md');
  assert.match(adr, /^# ADR 0001: /);
  const sections = [...adr.matchAll(/^## (.+)$/gm)].map((match) => match[1]);
  assert.deepEqual(sections, ['Contexto', 'Alternativas consideradas', 'Decisión', 'Estado', 'Consecuencias']);
  assert.deepEqual([...adr.matchAll(/^### ([A-Z])\. /gm)].map((match) => match[1]), ['A', 'B', 'C']);
  assert.match(adr, /^- \*\*Alternativa elegida:\*\* C$/m);
  assert.match(adr, /^\*\*Escenario:\*\* E1/m);
  // Una decisión sin ninguna consecuencia mala todavía no se analizó.
  assert.equal([...adr.matchAll(/^- \*\*Mala:\*\*/gm)].length >= 1, true);
});

test('las cifras del ADR son las que calcula el revisor', async () => {
  const { chainAvailability, parseChain } = await import('./availability.ts');
  const adr = read('case/adr/0001-registro-local-en-la-agencia.md');
  const percent = (file: string, digits: number) => (chainAvailability(parseChain(read(file))) * 100).toFixed(digits).replace('.', ',');
  assert.equal(adr.includes(`${percent('data/register-central.txt', 1)} %`), true);
  assert.equal(adr.includes(`${percent('data/register-backup-link.txt', 2)} %`), true);
});
cycles.test.tsDescargar cycles.test.ts
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { test } from 'node:test';
import {
  buildGraph,
  elementaryCycles,
  formatCycle,
  formatEdge,
  hasCycle,
  parseEdges,
  smallestCuts,
  stability,
  tangles,
  topologicalOrder,
  withoutEdges,
} from './cycles.ts';

const graphOf = (text: string) => buildGraph(parseEdges(text));
const apachi = () => graphOf(readFileSync(new URL('data/modules.txt', import.meta.url), 'utf8'));

test('un grafo sin ciclos tiene un orden en que cada módulo va después de lo que usa', () => {
  const graph = graphOf('main -> loans\nmain -> members\nloans -> members\n');
  assert.deepEqual(elementaryCycles(graph), []);
  assert.deepEqual(topologicalOrder(graph), ['members', 'loans', 'main']);
});

test('el ciclo más corto: dos módulos que se importan mutuamente', () => {
  const graph = graphOf('catalog -> orders\norders -> catalog\n');
  assert.deepEqual(elementaryCycles(graph).map(formatCycle), ['catalog -> orders -> catalog']);
  assert.equal(topologicalOrder(graph), undefined);
});

test('un ciclo largo se encuentra una sola vez, escrito desde su módulo menor', () => {
  const graph = graphOf('c -> a\na -> b\nb -> c\n');
  assert.deepEqual(elementaryCycles(graph).map(formatCycle), ['a -> b -> c -> a']);
});

test('Apachi tiene dos ciclos: uno de dos módulos y uno de tres', () => {
  assert.deepEqual(elementaryCycles(apachi()).map(formatCycle), [
    'billing -> shipments -> billing',
    'notifications -> shipments -> tracking -> notifications',
  ]);
});

test('los dos ciclos comparten shipments: cuatro módulos quedan enredados en un solo grupo', () => {
  assert.deepEqual(tangles(apachi()), [['billing', 'notifications', 'shipments', 'tracking']]);
});

test('los dos ciclos no comparten ninguna flecha: quitar una sola no alcanza', () => {
  const cuts = smallestCuts(apachi());
  assert.equal(cuts.length, 6); // una de las 2 flechas del primero y una de las 3 del segundo
  assert.equal(cuts.every((cut) => cut.length === 2), true);
  for (const edge of parseEdges('shipments -> billing\nbilling -> shipments\nnotifications -> shipments\n')) {
    assert.equal(hasCycle(withoutEdges(apachi(), [edge])), true, formatEdge(edge));
  }
});

test('la solución del apunte: sin shipments -> billing ni notifications -> shipments no quedan ciclos', () => {
  const fixed = withoutEdges(apachi(), parseEdges('shipments -> billing\nnotifications -> shipments\n'));
  assert.equal(hasCycle(fixed), false);
  assert.deepEqual(topologicalOrder(fixed), ['agencies', 'notifications', 'tariffs', 'tracking', 'shipments', 'billing']);
});

test('estabilidad: agencies no depende de nadie (I = 0) y, sin los ciclos, de billing no depende nadie (I = 1)', () => {
  const before = new Map(stability(apachi()).map((row) => [row.name, row]));
  assert.deepEqual(before.get('agencies'), { name: 'agencies', dependents: 3, dependencies: 0, instability: 0 });
  assert.deepEqual(before.get('shipments'), { name: 'shipments', dependents: 2, dependencies: 4, instability: 4 / 6 });

  const fixed = withoutEdges(apachi(), parseEdges('shipments -> billing\nnotifications -> shipments\n'));
  const after = new Map(stability(fixed).map((row) => [row.name, row]));
  assert.equal(after.get('billing')!.instability, 1);
  assert.equal(after.get('notifications')!.instability, 0);
});

test('un módulo que se importa a sí mismo también es un ciclo', () => {
  const graph = graphOf('a -> a\na -> b\n');
  assert.deepEqual(elementaryCycles(graph).map(formatCycle), ['a -> a']);
  assert.deepEqual(tangles(graph), [['a']]);
});

test('dos ciclos que comparten una flecha se rompen quitando esa sola', () => {
  // a -> b está en los dos: a -> b -> a  y  a -> b -> c -> a.
  const graph = graphOf('a -> b\nb -> a\nb -> c\nc -> a\n');
  assert.equal(elementaryCycles(graph).length, 2);
  assert.deepEqual(smallestCuts(graph).map((cut) => cut.map(formatEdge)), [['a -> b']]);
});

test('una flecha repetida cuenta una vez, y una línea mal escrita se rechaza', () => {
  assert.deepEqual([...graphOf('a -> b\na -> b\n').entries()], [['a', ['b']], ['b', []]]);
  assert.throws(() => parseEdges('a => b\n'), /Línea 1/);
  assert.throws(() => withoutEdges(apachi(), [{ from: 'agencies', to: 'shipments' }]), RangeError);
});
latency.test.tsDescargar latency.test.ts
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { test } from 'node:test';
import * as week2 from '../week-02/stats.ts';
import { expand, mean, parseTable, percentile, rank, spans, total, type Row } from './latency.ts';

const table = (name: string): Row[] => parseTable(readFileSync(new URL(`data/${name}`, import.meta.url), 'utf8'));

test('la posición del percentil es ceil(p/100 × n), contando desde 1', () => {
  assert.equal(rank(5, 30), 2); // 1,5 → 2
  assert.equal(rank(5, 40), 2); // 2,0 → 2
  assert.equal(rank(5, 50), 3); // 2,5 → 3
  assert.equal(rank(5, 100), 5);
  assert.equal(rank(20, 99), 20); // con 20 mediciones, el p99 es el máximo
});

test('cuando p/100 × n es entero, esa es la posición, aunque la cuenta en binario se pase por poco', () => {
  // En JavaScript, 7/100 * 100 da 7.000000000000001: un techo directo diría 8.
  assert.equal((7 / 100) * 100 > 7, true);
  assert.equal(rank(100, 7), 7);
  assert.equal(rank(2000, 94), 1880);
  assert.equal(rank(2000, 95), 1900);
});

test('los cinco valores de la semana 2: 15, 20, 35, 40 y 50 ms', () => {
  const rows: Row[] = [15, 20, 35, 40, 50].map((value) => ({ count: 1, value }));
  assert.equal(percentile(rows, 30), 20);
  assert.equal(percentile(rows, 40), 20);
  assert.equal(percentile(rows, 50), 35);
  assert.equal(percentile(rows, 100), 50);
});

test('el seguimiento de Apachi: el promedio es 204 ms y no describe a ningún pedido', () => {
  const rows = table('tracking-latencies.txt');
  assert.equal(total(rows), 2000);
  assert.equal(mean(rows), 204);
  assert.equal(rows.some((row) => row.value === 204), false);
  // 1 700 pedidos (85 %) tardaron menos de un tercio del promedio.
  assert.equal(rows[0]!.count / total(rows), 0.85);
});

test('el seguimiento de Apachi: p50 = 60, p90 = 250, p95 = 900 y p99 = 6 000 ms', () => {
  const rows = table('tracking-latencies.txt');
  assert.deepEqual(spans(rows).map((span) => [span.from, span.to, span.value]), [
    [1, 1700, 60],
    [1701, 1880, 250],
    [1881, 1970, 900],
    [1971, 2000, 6000],
  ]);
  assert.equal(percentile(rows, 50), 60);
  assert.equal(percentile(rows, 90), 250);
  assert.equal(percentile(rows, 95), 900);
  assert.equal(percentile(rows, 99), 6000);
  assert.equal(percentile(rows, 100), 6000);
});

test('el p95 no cumple la medida de E2 (500 ms), aunque el promedio y el p90 sí queden por debajo', () => {
  const rows = table('tracking-latencies.txt');
  assert.equal(mean(rows) < 500, true);
  assert.equal(percentile(rows, 90) < 500, true);
  assert.equal(percentile(rows, 95) < 500, false);
});

test('el percentil cambia de fila en un borde: p94 es 250 ms y p94,1 ya es 900 ms', () => {
  const rows = table('tracking-latencies.txt');
  assert.equal(percentile(rows, 94), 250);
  assert.equal(percentile(rows, 94.1), 900);
});

test('los percentiles no se promedian: dos instancias con p95 de 60 y 900 ms dan un p95 conjunto de 60 ms, no de 480', () => {
  const one = table('tracking-api-1.txt');
  const two = table('tracking-api-2.txt');
  assert.equal(percentile(one, 95), 60);
  assert.equal(percentile(two, 95), 900);
  const both = [...one, ...two];
  assert.equal(percentile(both, 95), 60);
  // Y el p96 conjunto ya es 900 ms: la posición 1 920 cae en los pedidos de api-2.
  assert.equal(percentile(both, 96), 900);
});

test('el orden de las filas no importa, y dos filas con el mismo valor se juntan', () => {
  const shuffled: Row[] = [
    { count: 30, value: 6000 },
    { count: 700, value: 60 },
    { count: 90, value: 900 },
    { count: 1000, value: 60 },
    { count: 180, value: 250 },
  ];
  assert.deepEqual(spans(shuffled), spans(table('tracking-latencies.txt')));
});

test('da lo mismo que stats.ts de la semana 2 sobre la lista completa', () => {
  for (const name of ['tracking-latencies.txt', 'tracking-api-1.txt', 'tracking-api-2.txt']) {
    const rows = table(name);
    const values = expand(rows);
    assert.equal(mean(rows), week2.mean(values));
    for (const p of [50, 90, 95, 99, 100]) assert.equal(percentile(rows, p), week2.percentile(values, p), `${name} p${p}`);
  }
});

test('una tabla mal escrita se rechaza con el número de línea', () => {
  assert.throws(() => parseTable('1700 60\nmuchos 250\n'), /Línea 2/);
  assert.throws(() => parseTable('0 60\n'), /Línea 1/);
  assert.throws(() => percentile([], 95), RangeError);
  assert.throws(() => rank(10, 0), RangeError);
});
coupling/quote.test.tsDescargar coupling/quote.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { quoteByPosition, quoteCents } from './quote.ts';

// Una encomienda de 3 kg con valor declarado de 200 soles, servicio normal:
// 800 + 3 × 150 + 1 % de 20 000 céntimos = 1 450 céntimos.

test('las dos versiones cobran lo mismo cuando se las llama bien', () => {
  assert.equal(quoteByPosition(3, 200, 1), 1450);
  assert.equal(quoteCents({ weightKg: 3, declaredValueCents: 20000, service: 'standard' }), 1450);
});

test('connascence de posición: con el peso y el valor al revés compila igual y cobra otra cosa', () => {
  // 200 kg con valor declarado de 3 soles: ningún error, y el precio sale más de veinte veces mayor.
  assert.equal(quoteByPosition(200, 3, 1), 30803);
});

test('connascence de significado: el valor declarado en céntimos compila igual y cobra un seguro cien veces mayor', () => {
  assert.equal(quoteByPosition(3, 20000, 1), 21250);
});

test('connascence de significado: un servicio que nadie definió se cobra como normal, sin avisar', () => {
  assert.equal(quoteByPosition(3, 200, 3), quoteByPosition(3, 200, 1));
});

test('con campos con nombre, el servicio express cuesta una vez y media', () => {
  assert.equal(quoteCents({ weightKg: 3, declaredValueCents: 20000, service: 'express' }), 2175);
});
deps/test/counter.test.tsDescargar deps/test/counter.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { createBilling } from '../src/billing/index.ts';
import { createCounter, type ReceiptIssuer, type Shipment } from '../src/shipments/index.ts';

const parcel = { originAgency: 'Tarma', destinationAgency: 'Lima', weightKg: 3, priceCents: 1450, recipientPhone: '999000111' };

test('el mostrador se prueba sin cargar billing: basta un emisor de mentira', async () => {
  const seen: Shipment[] = [];
  const receipts: ReceiptIssuer = {
    async issue(shipment) {
      seen.push(shipment);
      return 'X-1';
    },
  };
  const counter = createCounter({ receipts, nextCode: () => 'TAR-000001' });

  const result = await counter.register(parcel);

  assert.equal(result.receiptNumber, 'X-1');
  assert.deepEqual(seen, [{ ...parcel, code: 'TAR-000001' }]);
});

test('si el emisor falla, el registro falla: en esta versión el comprobante está en el camino', async () => {
  const receipts: ReceiptIssuer = {
    async issue() {
      throw new Error('el proveedor de facturación no responde');
    },
  };
  const counter = createCounter({ receipts, nextCode: () => 'TAR-000001' });
  await assert.rejects(counter.register(parcel), /no responde/);
});

test('billing implementa el port de shipments: numera los comprobantes y separa el IGV', async () => {
  const billing = createBilling('B001');
  const counter = createCounter({ receipts: billing, nextCode: () => 'TAR-000001' });

  const first = await counter.register(parcel);
  const second = await counter.register(parcel);

  assert.equal(first.receiptNumber, 'B001-00000001');
  assert.equal(second.receiptNumber, 'B001-00000002');
  // 1 450 × 18 / 118 = 221,19: el IGV incluido en el precio.
  assert.deepEqual(billing.issued()[0], { number: 'B001-00000001', shipmentCode: 'TAR-000001', totalCents: 1450, taxCents: 221 });
});

test('un peso de cero se rechaza antes de emitir nada', async () => {
  const billing = createBilling('B001');
  const counter = createCounter({ receipts: billing, nextCode: () => 'TAR-000001' });
  await assert.rejects(counter.register({ ...parcel, weightKg: 0 }), RangeError);
  assert.equal(billing.issued().length, 0);
});
deps/test/deps.test.tsDescargar deps/test/deps.test.ts
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { cpSync, mkdirSync, rmSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { fileURLToPath } from 'node:url';

// Las reglas de .dependency-cruiser.cjs: el ejemplo las cumple, y la variante
// de errors/cycle rompe dos (hay un ciclo, y una de sus dos flechas es la que
// el equipo decidió prohibir).

const deps = join(dirname(fileURLToPath(import.meta.url)), '..');
const week = join(deps, '..');

function run(command: string, args: string[], cwd: string): { status: number | null; output: string } {
  const result = spawnSync(command, args, { cwd, encoding: 'utf8' });
  return { status: result.status, output: result.stdout + result.stderr };
}

const cruise = (dir: string) => run('depcruise', ['src', '--config', '.dependency-cruiser.cjs'], dir);

/** Copia el ejemplo a build/ y le pone encima los archivos de errors/cycle. */
function cycleVariant(): string {
  const root = join(week, 'build', 'test-errors-cycle');
  const target = join(root, 'deps');
  rmSync(root, { recursive: true, force: true });
  mkdirSync(target, { recursive: true });
  for (const entry of ['src', '.dependency-cruiser.cjs']) cpSync(join(deps, entry), join(target, entry), { recursive: true });
  cpSync(join(week, 'errors', 'tsconfig.json'), join(root, 'tsconfig.json'));
  cpSync(join(week, 'errors', 'cycle', 'src'), join(target, 'src'), { recursive: true });
  return target;
}

test('el ejemplo cumple sus tres reglas', () => {
  const result = cruise(deps);
  assert.equal(result.status, 0, result.output);
  assert.match(result.output, /no dependency violations found/);
});

test('errors/cycle compila y funciona, y rompe no-circular y la regla de dirección', () => {
  const target = cycleVariant();

  // Un ciclo no es un error de tipos ni de ejecución: por eso no se anuncia solo.
  const types = run('tsc', ['-p', '..'], target);
  assert.equal(types.status, 0, types.output);
  const program = run('node', ['src/main.ts'], target);
  assert.equal(program.status, 0, program.output);
  assert.match(program.output, /Comprobante B001-00000001, IGV 221 céntimos/);

  const result = cruise(target);
  assert.notEqual(result.status, 0);
  assert.match(result.output, /error no-circular: /);
  assert.match(result.output, /error shipments-does-not-import-billing: src\/shipments\/counter\.ts → src\/billing\/index\.ts/);
  assert.match(result.output, /2 dependency violations \(2 errors, 0 warnings\)/);
});

Compilación

Cómo se compilan y ejecutan los ejemplos.

MakefileDescargar Makefile
# Semana 8: repaso antes del examen parcial. Se usa dentro del contenedor del
# curso. No hay laboratorio: son los revisores de las cuentas de los
# ejercicios resueltos del apunte, sobre un caso nuevo (Apachi).
#
#   make               no hay nada que preparar: muestra esta ayuda
#   make test          revisa los tipos (tsc) y corre las pruebas (*.test.ts),
#                      que comprueban lo que dice el apunte
#   make percentiles   la tabla de latencias del seguimiento: promedio y percentiles
#   make instances     la misma cuenta por instancia y con las dos juntas
#   make availability  la disponibilidad de registrar una encomienda, con el
#                      diseño actual y con tres alternativas
#   make cycles        los ciclos del grafo de módulos, y el grafo sin ellos
#   make deps          las reglas de dependencia del ejemplo de deps/ (pasan)
#   make errors        la variante con el ciclo (errors/cycle) y los escenarios
#                      mal escritos (errors/vague-scenarios.md): fallan a propósito
#   make case          revisa los documentos del caso (case/) con los revisores
#                      de las semanas 1, 2 y 7
#   make clean         borra build/

TESTS = $(wildcard *.test.ts coupling/*.test.ts deps/test/*.test.ts)

.PHONY: all test percentiles instances availability cycles deps errors case clean

all:
	@sed -n '2,/^$$/p' Makefile | sed 's/^# \{0,1\}//'

test:
	tsc -p .
	node --test $(TESTS)

percentiles:
	@node check.ts percentiles data/tracking-latencies.txt

instances:
	@echo "== api-1"
	@node check.ts percentiles data/tracking-api-1.txt
	@echo "== api-2"
	@node check.ts percentiles data/tracking-api-2.txt
	@echo "== las dos juntas"
	@node check.ts percentiles data/tracking-api-1.txt data/tracking-api-2.txt

availability:
	@for name in central deferred-effects backup-link agency-node; do \
		echo "== data/register-$$name.txt"; \
		node check.ts availability data/register-$$name.txt; \
	done

cycles:
	@node check.ts cycles data/modules.txt
	@echo
	@node check.ts cycles data/modules.txt --without "shipments -> billing" --without "notifications -> shipments"

deps:
	cd deps && depcruise src --config .dependency-cruiser.cjs

# La variante es el ejemplo con los archivos de errors/cycle encima. depcruise
# y el revisor de escenarios terminan con error cuando encuentran algo: aquí
# eso es lo que se quiere ver.
errors:
	@rm -rf build/errors/cycle; mkdir -p build/errors/cycle/deps
	@cp errors/tsconfig.json build/errors/cycle/
	@cp -r deps/src deps/.dependency-cruiser.cjs build/errors/cycle/deps/
	@cp -r errors/cycle/src build/errors/cycle/deps/
	@echo "== errors/cycle"
	@cd build/errors/cycle/deps && depcruise src --config .dependency-cruiser.cjs ; echo "depcruise terminó con código $$?"
	@echo "== errors/vague-scenarios.md"
	@node ../week-02/scenario-check.ts errors/vague-scenarios.md ; echo "scenario-check terminó con código $$?"

case:
	node ../week-02/scenario-check.ts case/scenarios.md
	node ../week-01/check-c4.ts case/context.md case/containers.md
	node ../week-07/check-adr.ts case/adr
	node ../week-07/check-atam.ts case/atam.md

clean:
	rm -rf build
package.jsonDescargar package.json
{"private": true, "type": "module"}
tsconfig.jsonDescargar tsconfig.json
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["*.ts", "coupling", "deps"]
}