117 lines
6.2 KiB
Markdown
117 lines
6.2 KiB
Markdown
# F-152 — Implementer evidence
|
|
|
|
## Problema
|
|
|
|
Los emails transaccionales de creación de cuenta y confirmación de orden no se enviaban:
|
|
- Al registrarse un usuario (`POST /auth/register`) no se disparaba el email de
|
|
bienvenida (`account_created`).
|
|
- Al confirmarse un pago (`POST /payments/webhook` → `PaymentSucceeded`) no se
|
|
enviaba el email de confirmación de orden (estado `PAID`).
|
|
|
|
SMTP se lee de `store_settings` (`smtp_host/port/secure/user/pass/from`) y la
|
|
capa de envío reusa `nodemailer` y el patrón de `sendOrderStatusEmail` /
|
|
`LoggingEmailProvider`.
|
|
|
|
## Cambios
|
|
|
|
### Identity — welcome email
|
|
- `project/src/modules/identity/domain/ports.ts`
|
|
- Nuevo puerto `WelcomeMailer`: `sendWelcome(input: { email: string; name?: string }): Promise<void>`
|
|
(`name` opcional: el dominio `User` no almacena nombre).
|
|
- `project/src/modules/identity/infrastructure/settings-welcome-mailer.ts` (nuevo)
|
|
- `SettingsWelcomeMailer(pool)` — lee SMTP de `store_settings`, usa `nodemailer`,
|
|
y función pura `buildWelcomeEmail` (verificable sin SMTP). Subject
|
|
`¡Bienvenido a Mercado de Vida!` coincide con la plantilla `account_created`.
|
|
Lanza `SMTP is not configured` cuando falta SMTP.
|
|
- `project/src/modules/identity/api/identity.routes.ts`
|
|
- `IdentityRoutesDeps.welcomeMailer?: WelcomeMailer`; en el handler de
|
|
`POST /auth/register` se despacha el email *fire-and-forget*
|
|
(`void mailer.sendWelcome(...).catch(request.log.warn(...))`). Best-effort:
|
|
un fallo SMTP se loguea (warning) y se traga; el registro nunca se rompe.
|
|
- `project/src/modules/identity/index.ts`
|
|
- Re-exporta `SettingsWelcomeMailer` (y `SettingsPasswordResetMailer`) para que
|
|
`build-app.ts` los importe desde el index (cumple R2 de boundaries).
|
|
- `project/src/app/build-app.ts`
|
|
- `welcomeMailer: new SettingsWelcomeMailer(deps.pool)` inyectado en
|
|
`IdentityRoutesDeps`.
|
|
|
|
### Payments — order confirmation
|
|
- `project/src/modules/payments/api/payments.routes.ts`
|
|
- En el handler de `POST /payments/webhook`, tras
|
|
`const outcome = await service.handleWebhook(event)`, si
|
|
`event.type === 'PaymentSucceeded' && event.orderId && outcome.kind === 'processed'`
|
|
se resuelve el email del cliente (`orders_orders.user_id` →
|
|
`identity_users.email`) y se llama `sendOrderStatusEmail(deps.pool, { to,
|
|
orderId, state: 'PAID' })` dentro de try/catch (log de advertencia si falla
|
|
SMTP/no-config). El gate `outcome.kind === 'processed'` asegura envío único
|
|
frente a webhooks duplicados (PaymentsService devuelve `{ kind: 'duplicate' }`
|
|
antes de cualquier transición de estado).
|
|
|
|
### Orders — barrel
|
|
- `project/src/modules/orders/index.ts`
|
|
- Re-exporta `sendOrderStatusEmail`, `buildOrderStatusEmail`,
|
|
`ORDER_STATE_LABELS` y `type OrderStatusNotificationInput` para que payments
|
|
los consuma sin deep-import (boundary clean).
|
|
|
|
### Notifications — consistencia de plantilla
|
|
- `project/src/modules/notifications/domain/notification.ts`
|
|
- Añadido `account_created` al union `EmailTemplate` y a los mapas SUBJECTS/BODIES
|
|
de `LoggingEmailProvider`.
|
|
- `project/src/modules/notifications/infrastructure/log-email-provider.ts`
|
|
- Añadido `account_created` a `SUBJECTS` y `BODIES`.
|
|
- `project/src/modules/notifications/api/notifications.routes.ts`
|
|
- Añadido `account_created` al enum del schema de `POST /notifications/dispatch`.
|
|
|
|
## Tests
|
|
|
|
- `project/src/modules/identity/infrastructure/settings-welcome-mailer.test.ts` (nuevo, 5 tests)
|
|
- `buildWelcomeEmail` incluye el email en el greeting y HTML-escapea el nombre
|
|
(XSS-safe).
|
|
- `SettingsWelcomeMailer.sendWelcome` (nodemailer mockeado): asserta que
|
|
`sendMail` se llama una sola vez con `to == email` y
|
|
`subject == '¡Bienvenido a Mercado de Vida!'` (plantilla `account_created`).
|
|
- Lanza `SMTP is not configured` cuando no hay SMTP (`readSmtpOptions`).
|
|
- `project/src/modules/orders/tests/orders-index.test.ts` (nuevo, 1 test)
|
|
- El barrel de `orders/index.ts` re-exporta `sendOrderStatusEmail`,
|
|
`buildOrderStatusEmail`, `ORDER_STATE_LABELS` y el tipo.
|
|
- `order-status-mailer.test.ts` cubre `buildOrderStatusEmail` / `ORDER_STATE_LABELS`
|
|
(`PAID` incluido) — preexistente, sin tocar.
|
|
|
|
## Verificación
|
|
|
|
```text
|
|
tsc --noEmit (project/tsconfig.json) ✅ 0 errores
|
|
prettier --check (archivos tocados) ✅ All matched files use Prettier code style
|
|
eslint (archivos tocados) ✅ 0 errores
|
|
lint:boundaries (node scripts/check-module-boundaries.mjs src) ✅ sin nuevas violaciones (queda SOLO la R1 preexistente de security.routes, ajena a F-152)
|
|
vitest run (suite completa) ✅ 197 passed | 56 skipped (253)
|
|
verify.sh ✅ exit 0
|
|
git diff --check ✅
|
|
```
|
|
|
|
## Decisiones
|
|
|
|
- **Dispatch del welcome email en el *route handler*, no en `RegisterUser`**:
|
|
la aceptación exige "se loguea un warning" ante fallo SMTP, pero `RegisterUser`
|
|
no posee logger. `identity.routes.ts` sí tiene `request.log`. Dispachar allí
|
|
best-effort (`fire-and-forget` + `.catch(request.log.warn)`) satisface
|
|
observabilidad y best-effort, siguiendo el precedente de `sendOrderStatusEmail`
|
|
en payments. `RegisterUser` se mantiene puro (orquestación de dominio).
|
|
- **Gate `outcome.kind === 'processed'`** garantiza idempotencia frente a webhooks
|
|
duplicados (PaymentsService devuelve `{ kind: 'duplicate' }` antes de cualquier
|
|
transición). Evita tabla de dedup adicional.
|
|
- **`buildWelcomeEmail` es pura + XSS-safe**: `name` se HTML-escapea (unit test)
|
|
para que la personalización no inyecte markup en el body.
|
|
- **Path gotcha `./domain` vs `../domain`**: el reader tool renderizó
|
|
`orders/index.ts` como `../domain/order.js` cuando el archivo real usa un solo
|
|
punto `./domain/order.js` (confirmado con `od -c`/`python3 repr`). El re-export
|
|
final se valida con typecheck (import resuelto correctamente).
|
|
|
|
## Estado runtime
|
|
|
|
No hay endpoint HTTP nuevo verificable en vivo más allá de los tests unitarios;
|
|
la entrega se valida por: (a) welcome email enviado al email registrado según el
|
|
test de `SettingsWelcomeMailer` (nodemailer mockeado), (b) orden transita a `PAID`
|
|
y se envía `sendOrderStatusEmail({ state: 'PAID' })` tras `PaymentSucceeded` con
|
|
`outcome.kind === 'processed'` (gate de dedup).
|