feat(F-001): scaffold modular monolith skeleton with boundary checker

- TypeScript + Fastify skeleton under project/ (src/modules, shared, infrastructure, app)
- scripts/check-module-boundaries.mjs enforcing module public-API rules (tested with fixtures)
- GET /health endpoint, error envelope without stack leakage
- specs/F-001-scaffold (SPEC/DESIGN/TASKS/TESTS), spec/tech.md dependency justification
- 30-ticket MercadoDeVida roadmap in backlog/features.json, spec/roadmap.md
- All gates approved: reviewer, security, qa; verify.sh green
This commit is contained in:
rikrdo
2026-08-14 21:46:54 +02:00
commit 1d4eebca54
76 changed files with 9430 additions and 0 deletions

9
spec/acceptance.md Normal file
View File

@@ -0,0 +1,9 @@
# Acceptance Criteria
Define criterios verificables por feature.
Formato recomendado:
- Feature ID:
- Escenario:
- Given / When / Then:
- Evidencia esperada (test/comando):

15
spec/product.md Normal file
View File

@@ -0,0 +1,15 @@
# Product Spec
## Problema
Describe el problema de negocio.
## Objetivo
Define el resultado esperado del producto.
## Usuarios
- Usuario principal:
- Usuario secundario:
## Alcance v1
- In scope:
- Out of scope:

52
spec/roadmap.md Normal file
View File

@@ -0,0 +1,52 @@
# MercadoDeVida vNext — Roadmap
Source of truth for intent: project/design_prompt.md
Source of truth for execution: backlog/features.json (one feature at a time, gates before done)
Stack decisions (fixed, boring):
- Backend: TypeScript + Node.js + Fastify (modular monolith)
- Frontend: Next.js + React + TypeScript + Tailwind (SSG/ISR for SEO pages)
- Database: PostgreSQL (source of truth) + Redis (cache only)
- Product code lives in project/
## Waves
### Wave 0 — Foundation (F-001 … F-004)
Skeleton, migrations, request context, config/flags. Nothing business yet.
Exit: build/lint/typecheck/test green, dev DB up with one command.
### Wave 1 — Identity & Users (F-005 … F-006)
Accounts, sessions, RBAC. Exit: customer and admin identities work.
### Wave 2 — Catalog (F-007 … F-012)
Categories → products → brands → variants/rich data → images → search.
Exit: full catalog model behind public module APIs, search replaceable.
### Wave 3 — Storefront & SEO (F-013 … F-015)
Next.js shell → catalog pages (SSG/ISR, stable URLs) → structured data, sitemap, redirects.
Exit: SEO-critical public surface is live and crawlable.
### Wave 4 — Commerce core (F-016 … F-023)
Inventory → pricing → cart → promotions → shipping → orders → checkout → payments.
This is the money path. Order matters; do not skip dependencies.
Exit: customer pays, order becomes PAID, stock is correct under concurrency.
### Wave 5 — Post-purchase & cross-cutting (F-024 … F-030)
Notifications, reviews, CMS, caching, security hardening, observability, E2E.
Exit: production-grade cross-cutting concerns with the money path protected end to end.
## Execution rules (from design_prompt.md)
1. NO FEATURE WITHOUT SPEC: each ticket produces specs/<feature>/SPEC.md, DESIGN.md, TASKS.md, TESTS.md during the design stage.
2. Smallest possible change; no unrelated refactors.
3. Every change reports expected blast radius before coding.
4. Modules communicate only through public interfaces or domain events.
5. Never trust frontend for price, stock, discount, payment status or user identity.
6. ./scripts/verify.sh green is a precondition for closing any ticket.

30
spec/tech.md Normal file
View File

@@ -0,0 +1,30 @@
# 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) |
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