41f144d7bd
- request_id generated or sanitized-propagated on every request (x-request-id)
- structured JSON logging (pino), one correlated line per request, injectable logger
- error envelope v2 { error: { statusCode, code, message, details? }, requestId }
- 5xx messages always generic; stack traces stay in server logs only
- explicit parseJson (zod) input validation hook at the API layer
- README HTTP contract section; deps justified in spec/tech.md
- all gates approved; verify.sh green
36 lines
2.0 KiB
Markdown
36 lines
2.0 KiB
Markdown
# Technical Spec — MercadoDeVida vNext
|
|
|
|
## Stack
|
|
- Lenguaje: TypeScript (strict) — backend y frontend
|
|
- Framework backend: Fastify 5 (monolito modular; elegido por tipado, simplicidad y ausencia de magia)
|
|
- Framework frontend: Next.js + React + Tailwind (llega en F-013; SSG/ISR para SEO)
|
|
- Runtime: Node.js >= 22
|
|
- Base de datos: PostgreSQL (fuente de verdad) + Redis (solo caché) — desde F-002
|
|
|
|
## Dependencias (justificación obligatoria por política de seguridad)
|
|
|
|
| Dependencia | Versión | Justificación |
|
|
|---|---|---|
|
|
| fastify | ^5.2 | Servidor HTTP tipado, maintained, sin magia; única dep de runtime en F-001 |
|
|
| typescript | ^5.7 | Tipado estricto (dev) |
|
|
| vitest | ^3 | Tests unit/integración TS-native (dev) |
|
|
| eslint + @eslint/js + typescript-eslint + eslint-config-prettier | ^9 / ^8 / ^10 | Linting estándar (dev) |
|
|
| prettier | ^3 | Formato consistente (dev) |
|
|
| pg | ^8 | Driver PostgreSQL estándar; única forma de hablar con la DB (F-002) |
|
|
| node-pg-migrate | ^8 | Migraciones SQL up/down trackeadas en DB; elegida sobre runner propio (no reinvención) y sobre Flyway/golang-migrate (toolchains ajenos a Node) (F-002) |
|
|
| @types/pg | ^8 | Tipos para pg (dev) (F-002) |
|
|
| pino | ^9 | Logging JSON estructurado; estándar del ecosistema Fastify, rápido y sin magia (F-003) |
|
|
| zod | ^4 | Validación explícita de inputs vía parseJson en handlers; sin decoradores ni magic binding (F-003) |
|
|
|
|
Regla: toda dependencia nueva debe agregarse a esta tabla con justificación en el ticket que la introduce.
|
|
|
|
## Restricciones
|
|
- Seguridad: nunca confiar en frontend para precio/stock/descuento/estado de pago; envelopes de error sin stack traces; sin secretos en repo
|
|
- Rendimiento: caché solo donde sea medible (F-027)
|
|
- Compatibilidad: URLs públicas estables /productos/<slug>, /categoria/<slug>, /marca/<slug>
|
|
|
|
## Observabilidad
|
|
- Logging: estructurado con request_id (F-003)
|
|
- Métricas: Prometheus con métricas de negocio (F-029)
|
|
- Alertas: fuera de alcance inicial
|