mercadodevida/spec/tech.md

F-153 — Tech Spec

Principles

• Associate the customer email to the order read model (not a per-request hack): OrderView.email is resolved once by the orders repository via a LEFT JOIN identity_users.
• Reuse the existing SQL pattern: orders/infrastructure/pg-order-repository.ts search already does LEFT JOIN identity_users u ON u.id = o.user_id — F-153 extends that to every order read so the email is always available on the view.
• Boundaries: identity_users is referenced only as a SQL table name (pre-existing in search); no TypeScript import crosses the identity/orders boundary. identity does not import orders; orders references identity_users table name (string) at infrastructure.
• NoUncheckedIndexedAccess is ON → index access returns T | undefined; use ! or ?? null when mapping rows.
• Backward compatible: email is an additive field on the serialized output; no state transition, no new migration, no endpoint change.

Changes

1. Domain — OrderView carries email

• orders/domain/order.ts: add email: string | null; to OrderView (Order itself unchanged — email is a denormalized read-model attribute, not a core domain field).

2. Infrastructure — resolve email in the repo

• orders/infrastructure/pg-order-repository.ts:
  • Add email: string | null to OrderRow.
  • Add helper toOrderView(row, items): OrderView = { ...toOrder(row), email: row.email, items }.
  • SELECT o.* → SELECT o.*, u.email with LEFT JOIN identity_users u ON u.id = o.user_id in findById, findByIdAndUserId, findAll, search.
  • Build every returned OrderView via toOrderView (so email is always set; null when the order has no linked identity_user).

3. API — expose + consume email

• orders/api/orders.routes.ts:
  • serializeOrder: add email: string | null to the param type and to the output (email: order.email).
  • Admin force-transition (POST /orders/:id/transitions/admin): replace the inline SELECT email FROM identity_users WHERE id = order.userId with const to = order.email; (single source of truth; the LEFT JOIN already resolved it). Keep the try/catch + warn and the "El cliente no tiene email asociado" fallback (now only when order.email is null).

Testing

• New orders/infrastructure/pg-order-repository.test.ts: mock pg.Pool, assert findById returns email from the JOIN when the linked identity_user has one, and null when there is no linked user.
• Update existing OrderView literals in tests (order-service, payments-service, checkout-service) to include email: null (additive field).
• order-status-mailer.test.ts (existing) remains green (no change to email senders).
• tsc --noEmit clean; prettier + eslint clean; lint:boundaries no new violations; vitest run full suite green; verify.sh green.