# Tinkuy

*Tinkuy* quiere decir *encuentro* en quechua. Es una plataforma de venta de
entradas para conciertos y partidos de fútbol en el Perú: publica los eventos
de varios locales, muestra qué asientos quedan, cobra con tarjeta o con Yape y
emite una entrada por asiento.

Esta es la versión 0: un monolito pequeño que funciona. Tiene una API HTTP en
JSON, una base de datos PostgreSQL, una pasarela de pagos de prueba que corre
como proceso aparte y una suite de pruebas. Está escrito en TypeScript y corre
directamente con Node.js 26, sin paso de compilación y sin frameworks: el
servidor es `node:http`, las pruebas son `node:test` y el único paquete es
`pg`, que ya viene en el contenedor del curso.

Es el punto de partida del proyecto. Durante el semestre le van a llegar
requisitos de calidad, y con cada uno van a tener que decidir qué parte de
esta arquitectura cambia. Antes de cambiarla hay que conocerla: léanla
completa, córranla y mídanla.

## Cómo correrlo

Todo se hace dentro del contenedor del curso (`./env/run.sh` desde la carpeta
del curso; Tinkuy queda en `/work/tinkuy`). PostgreSQL ya está corriendo ahí.
Hacen falta tres terminales: si el contenedor ya está abierto, `./env/run.sh`
abre otra shell en el mismo.

```sh
make db         # terminal 1: crea la base de datos tinkuy con sus datos de ejemplo
make gateway    # terminal 1: la pasarela de pagos de prueba, en el puerto 4000
make start      # terminal 2: Tinkuy, en http://localhost:3000
```

`make db` termina con el resumen de lo que cargó:

```
Semilla 7: 6 locales, 24 eventos, 75 secciones, 13080 asientos (3225 vendidos), 1303 órdenes, 1303 pagos, 3225 entradas, 1303 notificaciones
```

Y en la tercera terminal ya se puede comprar. Dos asientos de Preferencial
para el evento 1, con Yape:

```sh
curl -s localhost:3000/health
curl -s -X POST localhost:3000/orders -H 'content-type: application/json' -d '{
  "eventId": 1,
  "seatIds": [1001, 1002],
  "buyer": { "email": "rosa.quispe@correo.pe", "name": "Rosa Quispe" },
  "payment": { "method": "yape", "phone": "987654321", "approvalCode": "482913" }
}'
```

```
{"status":"ok"}
{"order":{"id":1304,"eventId":1,"status":"paid","buyer":{"email":"rosa.quispe@correo.pe","name":"Rosa Quispe"},"paymentMethod":"yape","subtotalCents":32000,"feeCents":0,"totalCents":32000,"createdAt":"2026-11-16T05:29:52.041Z"},"tickets":[{"id":3226,"code":"TKY-BFF01C12E772","seatId":1001,"sectionName":"Preferencial","row":"P","number":1,"priceCents":16000},{"id":3227,"code":"TKY-07983A7EA5B2","seatId":1002,"sectionName":"Preferencial","row":"P","number":2,"priceCents":16000}]}
```

Si alguien más pide el asiento 1001, ya no está:

```
{"error":{"code":"SEAT_NOT_AVAILABLE","message":"Ya no está disponible: asiento 1001"}}
```

Para leer mejor las respuestas, agreguen `| jq` al final del comando.

## La API

Todas las respuestas son JSON. Los montos van en céntimos de sol (`45000` es
S/ 450.00) y las fechas en UTC.

| Método y ruta | Qué hace | Respuestas |
|---|---|---|
| `GET /health` | Dice si el servidor está arriba | 200 `{ "status": "ok" }` |
| `GET /events?city=&kind=` | Lista los eventos, del más próximo al más lejano, con los asientos que le quedan a cada uno (`availableSeats`). Filtros opcionales: ciudad y tipo (`concert` o `match`) | 200 · 422 si `kind` no existe |
| `GET /events/:id` | El evento con su local, sus secciones (precio, asientos y asientos libres) y lo vendido en la última hora | 200 · 404 |
| `GET /events/:id/seats?section=` | Los asientos del evento con su estado (`available` o `sold`). Filtro opcional: el id de una sección | 200 · 404 · 422 |
| `POST /orders` | Compra de 1 a 6 asientos de un evento | 201 con la orden, sus entradas y el total · 402 si la pasarela rechaza el pago · 409 si algún asiento ya no está disponible o la venta no ha abierto · 422 si los datos no son válidos |
| `GET /orders/:id` | Una orden con sus entradas | 200 · 404 |
| `GET /reports/sales?eventId=` | Reporte de ventas de un evento: asientos vendidos e ingresos por sección, y ventas por hora | 200 · 404 · 422 |

Un error siempre tiene la misma forma: `{ "error": { "code": "...", "message": "..." } }`.

El cuerpo de `POST /orders`:

```json
{
  "eventId": 1,
  "seatIds": [1001, 1002],
  "buyer": { "email": "rosa.quispe@correo.pe", "name": "Rosa Quispe" },
  "payment": { "method": "card", "cardNumber": "4111111111111111", "holder": "ROSA QUISPE" }
}
```

`payment` depende del medio de pago:

- Tarjeta: `{ "method": "card", "cardNumber": "<16 dígitos>", "holder": "<nombre en la tarjeta>" }`.
- Yape: `{ "method": "yape", "phone": "<celular de 9 dígitos>", "approvalCode": "<código de 6 dígitos>" }`.

## Reglas del negocio

- Una orden es de un solo evento y lleva de 1 a 6 asientos, sin repetir.
- Solo se venden asientos de eventos con la venta abierta (`on_sale`). Un
  evento `scheduled` está anunciado, pero todavía no vende.
- El precio de un asiento es el de su sección. A la orden se le suma la
  comisión del medio de pago: con tarjeta, 3.5 % del subtotal más S/ 0.30; con
  Yape no hay comisión.
- Si la pasarela aprueba el cobro, los asientos pasan a `sold`, se emite una
  entrada por asiento, con su código, y se envía el correo de confirmación.
- Si la pasarela rechaza el cobro, la orden queda guardada como `failed` y los
  asientos siguen libres.
- El reporte de ventas cuenta solo las órdenes pagadas, y sus ingresos son el
  precio de las entradas, sin la comisión.

## Los datos de ejemplo

`make db` borra la base de datos `tinkuy`, la vuelve a crear con
`db/schema.sql` y la llena con `db/seed.ts`. Los datos son inventados y
deterministas: con la misma semilla salen exactamente los mismos
(`make db SEED=8` genera otros).

- 6 locales en Lima, Arequipa, Cusco y Trujillo, y 24 eventos entre conciertos
  y partidos.
- **El evento 1 es el grande**: el concierto de Killa Sónica en el Estadio
  Nacional, con 4 secciones y 2000 asientos (ids del 1 al 2000), todos libres
  y con la venta abierta. Es el que se usa para las pruebas de carga.
- Los demás eventos tienen entre 200 y 800 asientos. Los eventos del 2 al 22
  ya vendieron cerca de un tercio, con sus órdenes, pagos, entradas y correos.
  Los eventos 23 y 24 están anunciados y todavía no venden.

## La pasarela de pagos de prueba

En producción, Tinkuy cobraría a través del servicio de un banco o de un
procesador de pagos. Aquí ese servicio es `tools/fake-gateway.ts`, un proceso
aparte que recibe `POST /charges` y responde `approved` o `declined`. Es
determinista:

- rechaza las tarjetas cuyo número termina en `0000`;
- rechaza los pagos con Yape de celulares que terminan en `000`;
- ya acepta también cobros con Plin (`{ "method": "plin", "plin": { "phone": "<celular>" } }`, con la misma regla de rechazo), aunque Tinkuy todavía no ofrece ese medio de pago;
- aprueba todo lo demás;
- si el cobro llega con la cabecera `Idempotency-Key`, un segundo pedido con la misma clave no cobra de nuevo: recibe la respuesta del primero. Tinkuy todavía no la envía.

Se puede volver lenta o inestable con variables de entorno, por ejemplo
`GATEWAY_LATENCY_MS=2000 make gateway`.

## Variables de entorno

| Variable | Por omisión | Para qué |
|---|---|---|
| `PORT` | `3000` | Puerto de Tinkuy |
| `TINKUY_DB` | `tinkuy` | Base de datos (el host y el usuario son los del contenedor: `PGHOST`, `PGUSER`) |
| `GATEWAY_URL` | `http://localhost:4000` | Dónde está la pasarela de pagos |
| `EMAIL_LATENCY_MS` | `120` | Lo que tarda el servidor de correo simulado en aceptar un mensaje |
| `EMAIL_FAIL_EVERY` | `0` | El servidor de correo rechaza un mensaje de cada N (0 = nunca) |
| `GATEWAY_PORT` | `4000` | Puerto de la pasarela |
| `GATEWAY_LATENCY_MS` | `80` | Demora de cada respuesta de la pasarela |
| `GATEWAY_FAIL_EVERY` | `0` | La pasarela responde 503 en uno de cada N pedidos (0 = nunca) |

Las tres últimas son de la pasarela (`make gateway`); las demás, de Tinkuy
(`make start`).

## Cómo está organizado

```
tinkuy/
├── Makefile                 las tareas de todos los días
├── .dependency-cruiser.cjs  las reglas de dependencia entre módulos
├── db/
│   ├── schema.sql           tablas, restricciones e índices
│   └── seed.ts              los datos de ejemplo
├── src/
│   ├── main.ts              arranca el servidor
│   ├── config.ts            configuración desde variables de entorno
│   ├── db.ts                acceso a PostgreSQL
│   ├── errors.ts            los errores que la API sabe explicar
│   ├── log.ts               mensajes del servidor
│   ├── http/                router sobre node:http, JSON y un handler por endpoint
│   ├── catalog/             locales, eventos, secciones, asientos y disponibilidad
│   ├── orders/              la compra: validación, comisión, orden, ítems y entradas
│   ├── payments/            cliente de la pasarela de pagos
│   ├── notifications/       correo de confirmación
│   └── reports/             reporte de ventas
├── tools/
│   ├── fake-gateway.ts      la pasarela de pagos de prueba
│   └── oversell.ts          50 órdenes a la vez para un mismo asiento
├── load/
│   ├── browse.js            k6: gente mirando el catálogo
│   └── sale.js              k6: la apertura de ventas del evento 1
└── test/                    pruebas con node:test contra la base de datos tinkuy_test
```

Tablas: `venues`, `events`, `sections`, `seats`, `orders`, `order_items`,
`payments`, `tickets` y `notifications`. Para mirarlas: `psql tinkuy`.

## Tareas

| Comando | Qué hace |
|---|---|
| `make db` | Borra y crea la base de datos `tinkuy`, con su esquema y sus datos de ejemplo |
| `make start` | Levanta Tinkuy en `http://localhost:3000` |
| `make gateway` | Levanta la pasarela de pagos de prueba en el puerto 4000 |
| `make test` | Corre las pruebas. Crea su propia base de datos (`tinkuy_test`) y levanta el servidor y una pasarela dentro del proceso de pruebas: no necesita nada corriendo ni toca la base de datos `tinkuy` |
| `make typecheck` | Revisa los tipos con `tsc` |
| `make check` | `typecheck` + `test` |
| `make deps` | Comprueba las reglas de `.dependency-cruiser.cjs` con dependency-cruiser |
| `make load-browse` | Prueba de carga con k6: hasta 50 usuarios mirando el catálogo durante 30 segundos |
| `make load-sale` | Prueba de carga con k6: 200 compradores sobre el evento 1 durante 30 segundos |
| `make oversell` | Manda 50 órdenes a la vez para un mismo asiento y dice cuántas se aceptaron y cuántas entradas se emitieron |
| `make clean` | Borra las bases de datos `tinkuy` y `tinkuy_test` |

`make load-browse`, `make load-sale` y `make oversell` trabajan contra un
Tinkuy que ya está corriendo: necesitan `make start` y `make gateway` en otras
terminales (`BASE_URL` cambia a dónde apuntan). Las pruebas de carga y
`make oversell` venden asientos de verdad en la base de datos: corran
`make db` antes de repetirlas, para medir siempre desde el mismo punto.

Los scripts de k6 no definen umbrales: solo miden. Los números dependen de la
máquina, así que cuando reporten una medición digan en cuál la hicieron y
comparen siempre contra otra medición de la misma máquina.

`make check` pasa en esta versión. `make deps` no: reporta las dependencias
que hoy violan las reglas, y por eso todavía no forma parte de `make check`.
