feat(F-106): completed feature

2026-08-21 09:27:55 +02:00
parent 5458789634
commit dca7c3214f
21 changed files with 958 additions and 73 deletions
--- a/project/apps/admin/src/app/(dashboard)/orders/[id]/page.tsx
+++ b/project/apps/admin/src/app/(dashboard)/orders/[id]/page.tsx
@@ -1,9 +1,9 @@
 'use client';
 import { useState, useEffect, useCallback } from 'react';
-import { useParams, useRouter } from 'next/navigation';
+import { useParams } from 'next/navigation';
 import Link from 'next/link';
-import type { Order, OrderState } from '@/types';
-import { ordersApi } from '@/lib/api-client';
+import type { Order, OrderState, Product } from '@/types';
+import { ordersApi, productsApi } from '@/lib/api-client';

 const STATE_LABELS: Record<OrderState, string> = {
  PENDING: 'Pendiente',
@@ -53,19 +53,39 @@ const ACTION_LABELS: Record<OrderState, string> = {
  PARTIALLY_REFUNDED: 'Reembolso parcial',
 };

+interface DraftItem {
+  variantId: string;
+  productId: string;
+  sku: string;
+  name: string;
+  quantity: number;
+}
+
 function formatPrice(cents: number) {
  return `€${(cents / 100).toFixed(2)}`;
 }

 export default function OrderDetailPage() {
  const { id } = useParams<{ id: string }>();
-  const router = useRouter();
  const [order, setOrder] = useState<Order | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState('');
  const [transitioning, setTransitioning] = useState(false);
  const [showConfirm, setShowConfirm] = useState<OrderState | null>(null);
  const [confirmReason, setConfirmReason] = useState('');
+  const [trackingInput, setTrackingInput] = useState('');
+  const [notification, setNotification] = useState<{ ok: boolean; message: string } | null>(null);
+
+  // Edición de artículos
+  const [editing, setEditing] = useState(false);
+  const [draftItems, setDraftItems] = useState<DraftItem[]>([]);
+  const [savingItems, setSavingItems] = useState(false);
+  const [itemsError, setItemsError] = useState('');
+  const [productQuery, setProductQuery] = useState('');
+  const [searchResults, setSearchResults] = useState<Product[]>([]);
+  const [searching, setSearching] = useState(false);
+  const [addingProductId, setAddingProductId] = useState<string | null>(null);
+  const [addingVariants, setAddingVariants] = useState<{ id: string; sku: string }[]>([]);

  const load = useCallback(async () => {
    setLoading(true);
@@ -83,12 +103,22 @@ export default function OrderDetailPage() {
  useEffect(() => { load(); }, [load]);

  const handleTransition = async (nextState: OrderState) => {
+    if (nextState === 'SHIPPED' && !trackingInput.trim()) return;
    setTransitioning(true);
    try {
-      const updated = await ordersApi.transition(id, nextState);
+      const updated = await ordersApi.transition(id, nextState, trackingInput);
      setOrder(updated);
      setShowConfirm(null);
      setConfirmReason('');
+      setTrackingInput('');
+      if (updated.notified) {
+        setNotification({ ok: true, message: 'Cliente notificado por email.' });
+      } else {
+        setNotification({
+          ok: false,
+          message: updated.notificationError || 'No se pudo notificar al cliente por email.',
+        });
+      }
    } catch (err) {
      alert(err instanceof Error ? err.message : 'Error al cambiar estado');
    } finally {
@@ -96,6 +126,108 @@ export default function OrderDetailPage() {
    }
  };

+  const startEditing = () => {
+    if (!order) return;
+    setDraftItems(
+      order.items.map((item) => ({
+        variantId: item.variantId,
+        productId: item.productId,
+        sku: item.sku,
+        name: item.name,
+        quantity: item.quantity,
+      })),
+    );
+    setItemsError('');
+    setEditing(true);
+  };
+
+  const updateDraftQuantity = (variantId: string, quantity: number) => {
+    setDraftItems((prev) =>
+      prev.map((item) =>
+        item.variantId === variantId
+          ? { ...item, quantity: Math.max(1, Math.min(999, quantity || 1)) }
+          : item,
+      ),
+    );
+  };
+
+  const removeDraftItem = (variantId: string) => {
+    setDraftItems((prev) => prev.filter((item) => item.variantId !== variantId));
+  };
+
+  const searchProducts = useCallback(async (query: string) => {
+    setProductQuery(query);
+    if (query.trim().length < 2) {
+      setSearchResults([]);
+      return;
+    }
+    setSearching(true);
+    try {
+      const result = await productsApi.list({ q: query.trim(), limit: 8 });
+      setSearchResults(result.items ?? []);
+    } catch {
+      setSearchResults([]);
+    } finally {
+      setSearching(false);
+    }
+  }, []);
+
+  const pickProductForAdd = async (product: Product) => {
+    setAddingProductId(product.id);
+    setAddingVariants([]);
+    try {
+      const result = await productsApi.getVariants(product.id);
+      const variants = (result.items ?? []).map((variant) => ({ id: variant.id, sku: variant.sku }));
+      if (variants.length === 1) {
+        addDraftItem(variants[0].id, product.id, variants[0].sku, product.name);
+        setAddingProductId(null);
+      } else {
+        setAddingVariants(variants);
+      }
+    } catch (err) {
+      setItemsError(err instanceof Error ? err.message : 'Error al cargar variantes');
+      setAddingProductId(null);
+    }
+  };
+
+  const addDraftItem = (variantId: string, productId: string, sku: string, name: string) => {
+    setDraftItems((prev) => {
+      const existing = prev.find((item) => item.variantId === variantId);
+      if (existing) {
+        return prev.map((item) =>
+          item.variantId === variantId ? { ...item, quantity: Math.min(999, item.quantity + 1) } : item,
+        );
+      }
+      return [...prev, { variantId, productId, sku, name, quantity: 1 }];
+    });
+    setSearchResults([]);
+    setProductQuery('');
+    setAddingProductId(null);
+    setAddingVariants([]);
+    setItemsError('');
+  };
+
+  const saveItems = async () => {
+    if (draftItems.length === 0) {
+      setItemsError('El pedido debe tener al menos un artículo');
+      return;
+    }
+    setSavingItems(true);
+    setItemsError('');
+    try {
+      const updated = await ordersApi.editItems(
+        id,
+        draftItems.map((item) => ({ variantId: item.variantId, quantity: item.quantity })),
+      );
+      setOrder(updated);
+      setEditing(false);
+    } catch (err) {
+      setItemsError(err instanceof Error ? err.message : 'Error al guardar artículos');
+    } finally {
+      setSavingItems(false);
+    }
+  };
+
  if (loading) {
    return (
      <div className="flex items-center justify-center min-h-64">
@@ -117,6 +249,7 @@ export default function OrderDetailPage() {

  const currentState = order.state as OrderState;
  const allowed = ALLOWED_TRANSITIONS[currentState] ?? [];
+  const itemsEditable = currentState !== 'CANCELLED' && currentState !== 'REFUNDED';

  return (
    <div className="space-y-6">
@@ -142,6 +275,20 @@ export default function OrderDetailPage() {
        </span>
      </div>

+      {/* Notification result */}
+      {notification && (
+        <div
+          className={`flex items-center justify-between px-4 py-3 rounded-xl text-sm border ${
+            notification.ok
+              ? 'bg-green-50 border-green-200 text-green-800'
+              : 'bg-amber-50 border-amber-200 text-amber-800'
+          }`}
+        >
+          <span>{notification.message}</span>
+          <button onClick={() => setNotification(null)} className="ml-4 font-bold opacity-60 hover:opacity-100">✕</button>
+        </div>
+      )}
+
      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
        {/* Main content */}
        <div className="lg:col-span-2 space-y-6">
@@ -153,7 +300,7 @@ export default function OrderDetailPage() {
                {allowed.map((next) => (
                  <button
                    key={next}
-                    onClick={() => setShowConfirm(next)}
+                    onClick={() => { setShowConfirm(next); setNotification(null); }}
                    disabled={transitioning}
                    className="px-4 py-2 bg-[#2D6A4F] hover:bg-[#1B4332] disabled:opacity-50 text-white text-sm font-semibold rounded-xl transition-colors"
                  >
@@ -166,23 +313,135 @@ export default function OrderDetailPage() {

          {/* Order items */}
          <div className="bg-white border border-gray-200 rounded-xl p-6">
-            <h2 className="font-bold text-gray-900 mb-4">Productos</h2>
-            <div className="space-y-3">
-              {order.items.map((item) => (
-                <div key={item.id} className="flex justify-between items-start py-2 border-b border-gray-50 last:border-0">
-                  <div className="flex-1 min-w-0">
-                    <p className="text-sm font-medium text-gray-900">{item.name}</p>
-                    <p className="text-xs text-gray-400">
-                      {item.quantity} × {formatPrice(item.unitPriceCents)}
-                      {item.discountCents > 0 && ` (-${formatPrice(item.discountCents)})`}
+            <div className="flex items-center justify-between mb-4">
+              <h2 className="font-bold text-gray-900">Productos</h2>
+              {itemsEditable && !editing && (
+                <button
+                  onClick={startEditing}
+                  className="px-3 py-1.5 text-sm font-semibold text-[#2D6A4F] border border-[#2D6A4F] rounded-lg hover:bg-[#2D6A4F]/5 transition-colors"
+                >
+                  ✏️ Editar artículos
+                </button>
+              )}
+            </div>
+
+            {!editing ? (
+              <div className="space-y-3">
+                {order.items.map((item) => (
+                  <div key={item.id} className="flex justify-between items-start py-2 border-b border-gray-50 last:border-0">
+                    <div className="flex-1 min-w-0">
+                      <p className="text-sm font-medium text-gray-900">{item.name}</p>
+                      <p className="text-xs text-gray-400">
+                        {item.quantity} × {formatPrice(item.unitPriceCents)}
+                        {item.discountCents > 0 && ` (-${formatPrice(item.discountCents)})`}
+                      </p>
+                    </div>
+                    <p className="text-sm font-bold text-gray-900 ml-4">
+                      {formatPrice((item.unitPriceCents - item.discountCents) * item.quantity)}
                    </p>
                  </div>
-                  <p className="text-sm font-bold text-gray-900 ml-4">
-                    {formatPrice((item.unitPriceCents - item.discountCents) * item.quantity)}
-                  </p>
+                ))}
+              </div>
+            ) : (
+              <div className="space-y-4">
+                <div className="space-y-3">
+                  {draftItems.map((item) => (
+                    <div key={item.variantId} className="flex items-center gap-3 py-2 border-b border-gray-50 last:border-0">
+                      <div className="flex-1 min-w-0">
+                        <p className="text-sm font-medium text-gray-900 truncate">{item.name}</p>
+                        <p className="text-xs text-gray-400 font-mono">{item.sku}</p>
+                      </div>
+                      <input
+                        type="number"
+                        min={1}
+                        max={999}
+                        value={item.quantity}
+                        onChange={(e) => updateDraftQuantity(item.variantId, Number(e.target.value))}
+                        className="w-20 px-2 py-1.5 border border-gray-300 rounded-lg text-sm text-right focus:ring-2 focus:ring-[#2D6A4F] outline-none"
+                      />
+                      <button
+                        onClick={() => removeDraftItem(item.variantId)}
+                        disabled={draftItems.length === 1}
+                        title="Quitar artículo"
+                        className="p-1.5 text-red-500 hover:bg-red-50 rounded-lg disabled:opacity-30 disabled:cursor-not-allowed"
+                      >
+                        🗑️
+                      </button>
+                    </div>
+                  ))}
+                  {draftItems.length === 0 && (
+                    <p className="text-sm text-gray-400 py-2">Sin artículos. Añade al menos uno.</p>
+                  )}
                </div>
-              ))}
-            </div>
+
+                {/* Add product */}
+                <div className="border-t border-gray-100 pt-4">
+                  <label className="text-xs font-semibold text-gray-500 uppercase tracking-wide">Añadir producto</label>
+                  <input
+                    type="search"
+                    value={productQuery}
+                    onChange={(e) => { searchProducts(e.target.value); }}
+                    placeholder="Buscar por nombre o SKU (mín. 2 caracteres)…"
+                    className="mt-1 w-full px-3 py-2 border border-gray-300 rounded-xl text-sm focus:ring-2 focus:ring-[#2D6A4F] outline-none"
+                  />
+                  {searching && <p className="text-xs text-gray-400 mt-2">Buscando…</p>}
+                  {!searching && searchResults.length > 0 && (
+                    <ul className="mt-2 border border-gray-200 rounded-xl divide-y divide-gray-100 max-h-56 overflow-auto">
+                      {searchResults.map((product) => (
+                        <li key={product.id}>
+                          {addingProductId === product.id && addingVariants.length > 0 ? (
+                            <div className="px-3 py-2">
+                              <p className="text-sm font-medium text-gray-900">{product.name}</p>
+                              <div className="flex flex-wrap gap-2 mt-1">
+                                {addingVariants.map((variant) => (
+                                  <button
+                                    key={variant.id}
+                                    onClick={() => addDraftItem(variant.id, product.id, variant.sku, product.name)}
+                                    className="px-2 py-1 text-xs font-mono bg-gray-100 hover:bg-[#2D6A4F] hover:text-white rounded-lg transition-colors"
+                                  >
+                                    {variant.sku}
+                                  </button>
+                                ))}
+                              </div>
+                            </div>
+                          ) : (
+                            <button
+                              onClick={() => { pickProductForAdd(product); }}
+                              disabled={addingProductId !== null}
+                              className="w-full text-left px-3 py-2 text-sm text-gray-800 hover:bg-gray-50 disabled:opacity-50"
+                            >
+                              {product.name}
+                            </button>
+                          )}
+                        </li>
+                      ))}
+                    </ul>
+                  )}
+                </div>
+
+                {itemsError && <p className="text-sm text-red-600">{itemsError}</p>}
+
+                <div className="flex gap-3 justify-end border-t border-gray-100 pt-4">
+                  <button
+                    onClick={() => { setEditing(false); setItemsError(''); }}
+                    disabled={savingItems}
+                    className="px-4 py-2 text-sm text-gray-600 hover:text-gray-900 transition-colors"
+                  >
+                    Cancelar
+                  </button>
+                  <button
+                    onClick={saveItems}
+                    disabled={savingItems || draftItems.length === 0}
+                    className="px-4 py-2 bg-[#2D6A4F] hover:bg-[#1B4332] disabled:opacity-50 text-white text-sm font-semibold rounded-xl transition-colors"
+                  >
+                    {savingItems ? 'Guardando…' : 'Guardar artículos'}
+                  </button>
+                </div>
+                <p className="text-xs text-gray-400">
+                  Los precios e IVA se recalculan con las tarifas vigentes al guardar.
+                </p>
+              </div>
+            )}
          </div>
        </div>

@@ -211,6 +470,12 @@ export default function OrderDetailPage() {
                <span className="text-xl font-bold text-[#2D6A4F]">{formatPrice(order.totalCents)}</span>
              </div>
            </div>
+            {order.trackingNumber && (
+              <div className="mt-4 border-t border-gray-100 pt-3">
+                <p className="text-xs font-semibold text-gray-500 uppercase tracking-wide">Seguimiento</p>
+                <p className="text-sm font-mono text-gray-900 mt-1">{order.trackingNumber}</p>
+              </div>
+            )}
          </div>

          {/* Timeline */}
@@ -239,8 +504,23 @@ export default function OrderDetailPage() {
              Confirmar cambio de estado
            </h3>
            <p className="text-sm text-gray-600 mb-4">
-              ¿{ACTION_LABELS[showConfirm] ?? showConfirm}?
+              ¿{ACTION_LABELS[showConfirm] ?? showConfirm}? Se notificará al cliente por email.
            </p>
+            {showConfirm === 'SHIPPED' && (
+              <div className="mb-4">
+                <label className="block text-sm font-medium text-gray-700 mb-1">
+                  Número de seguimiento <span className="text-red-500">*</span>
+                </label>
+                <input
+                  type="text"
+                  value={trackingInput}
+                  onChange={(e) => setTrackingInput(e.target.value)}
+                  placeholder="p. ej. PQ123456789ES"
+                  maxLength={120}
+                  className="w-full px-3 py-2 border border-gray-300 rounded-xl text-sm focus:ring-2 focus:ring-[#2D6A4F] outline-none"
+                />
+              </div>
+            )}
            {(showConfirm === 'CANCELLED' || showConfirm === 'REFUNDED') && (
              <textarea
                value={confirmReason}
@@ -252,14 +532,14 @@ export default function OrderDetailPage() {
            )}
            <div className="flex gap-3 justify-end">
              <button
-                onClick={() => { setShowConfirm(null); setConfirmReason(''); }}
+                onClick={() => { setShowConfirm(null); setConfirmReason(''); setTrackingInput(''); }}
                className="px-4 py-2 text-sm text-gray-600 hover:text-gray-900 transition-colors"
              >
                Cancelar
              </button>
              <button
                onClick={() => handleTransition(showConfirm)}
-                disabled={transitioning}
+                disabled={transitioning || (showConfirm === 'SHIPPED' && !trackingInput.trim())}
                className="px-4 py-2 bg-[#2D6A4F] hover:bg-[#1B4332] disabled:opacity-50 text-white text-sm font-semibold rounded-xl transition-colors"
              >
                {transitioning ? 'Guardando...' : 'Confirmar'}
--- a/project/apps/admin/src/lib/api-client.ts
+++ b/project/apps/admin/src/lib/api-client.ts
@@ -106,8 +106,13 @@ export const ordersApi = {
    ).then((data) => (Array.isArray(data) ? { items: data, total: data.length } : data));
  },
  get: (id: string) => api.get<import('@/types').Order>(`/api/orders/${id}`),
-  transition: (id: string, state: string) =>
-    api.post<import('@/types').Order>(`/api/orders/${id}/transitions`, { state }),
+  transition: (id: string, state: string, trackingNumber?: string) =>
+    api.post<import('@/types').Order & { notified?: boolean; notificationError?: string }>(
+      `/api/orders/${id}/transitions`,
+      trackingNumber?.trim() ? { state, trackingNumber: trackingNumber.trim() } : { state },
+    ),
+  editItems: (id: string, items: { variantId: string; quantity: number }[]) =>
+    api.put<import('@/types').Order>(`/api/orders/${id}/items`, { items }),
 };

 // ── Customers ─────────────────────────────────────────────────────────────────
--- a/project/apps/admin/src/types/index.ts
+++ b/project/apps/admin/src/types/index.ts
@@ -108,6 +108,7 @@ export interface Order {
  discountCents: number;
  taxCents: number;
  totalCents: number;
+  trackingNumber?: string | null;
  idempotencyKey: string | null;
  items: OrderItem[];
  createdAt: string;
--- a/project/apps/admin/tsconfig.tsbuildinfo
+++ b/project/apps/admin/tsconfig.tsbuildinfo
--- a/project/migrations/036_order_tracking_number.js
+++ b/project/migrations/036_order_tracking_number.js
@@ -0,0 +1,15 @@
+/**
+ * Adds shipment tracking to orders. The tracking number is set when an order
+ * transitions to SHIPPED and is included in the customer notification.
+ * @param {import('node-pg-migrate').MigrationBuilder} pgm
+ */
+export const up = (pgm) => {
+  pgm.sql(`
+    ALTER TABLE orders_orders
+    ADD COLUMN IF NOT EXISTS tracking_number text NULL DEFAULT NULL
+  `);
+};
+
+export const down = (pgm) => {
+  pgm.sql(`ALTER TABLE orders_orders DROP COLUMN IF EXISTS tracking_number`);
+};
--- a/project/src/modules/orders/api/orders.routes.ts
+++ b/project/src/modules/orders/api/orders.routes.ts
@@ -12,6 +12,7 @@ import { OrderNotFoundError, OrderStateTransitionError } from '../domain/errors.
 import type { OrderState } from '../domain/order.js';
 import { PgOrderRepository } from '../infrastructure/pg-order-repository.js';
 import { NoOpOrderEventPublisher } from '../infrastructure/no-op-event-publisher.js';
+import { sendOrderStatusEmail } from '../infrastructure/order-status-mailer.js';

 export interface OrdersRoutesDeps {
  pool: pg.Pool;
@@ -225,6 +226,7 @@ export async function registerOrdersRoutes(
            'PARTIALLY_REFUNDED',
          ],
        },
+        trackingNumber: { type: 'string', maxLength: 120, description: 'Número de seguimiento del envío (obligatorio al marcar como Enviado)' },
      },
    },
    response: { 401: errorSchema, 403: errorSchema, 404: errorSchema },
@@ -236,15 +238,157 @@ export async function registerOrdersRoutes(
      const user = await deps.authenticate(request);
      requireRole(user, 'admin');
      const { id } = parseJson(orderIdParamSchema, request.params);
-      const { state } = parseJson(transitionSchema, request.body);
+      const { state, trackingNumber } = parseJson(
+        transitionSchema.extend({ trackingNumber: z.string().min(1).max(120).optional() }),
+        request.body,
+      );
+      if (state === 'SHIPPED' && !trackingNumber?.trim()) {
+        throw new AppError(422, 'TRACKING_NUMBER_REQUIRED', 'Indica el número de seguimiento para marcar el pedido como enviado');
+      }
+      let order;
      try {
-        const order = await service.transitionAdmin(id, state as OrderState);
-        return reply.send(serializeOrder(order));
+        order = await service.transitionAdmin(id, state as OrderState, trackingNumber?.trim() || undefined);
      } catch (error) {
        throw mapOrderError(error);
      }
+      // Notificar al cliente el cambio de estado (sin bloquear la transición).
+      let notified = false;
+      let notificationError = '';
+      try {
+        const emailRow = await deps.pool.query<{ email: string }>(
+          'SELECT email FROM identity_users WHERE id = $1',
+          [order.userId],
+        );
+        const to = emailRow.rows[0]?.email;
+        if (to) {
+          await sendOrderStatusEmail(deps.pool, {
+            to,
+            orderId: order.id,
+            state: order.state,
+            trackingNumber: order.trackingNumber,
+          });
+          notified = true;
+        } else {
+          notificationError = 'El cliente no tiene email asociado';
+        }
+      } catch (error) {
+        notificationError = error instanceof Error ? error.message : 'No se pudo enviar el email';
+        request.log.warn({ err: error, orderId: order.id }, 'order_status_email_failed');
+      }
+      return reply.send({ ...serializeOrder(order), notified, notificationError: notificationError || undefined });
    },
  );
+
+  const editItemsSchema: FastifySchema = {
+    tags: ['Orders'],
+    summary: 'Edit order items (admin)',
+    description:
+      'Reemplaza los artículos del pedido (agregar/quitar productos y ajustar cantidades). Los totales se recalculan con los precios e IVA actuales.',
+    params: {
+      type: 'object',
+      required: ['id'],
+      properties: { id: { type: 'string', format: 'uuid' } },
+    },
+    body: { type: 'object' },
+    response: { 401: errorSchema, 403: errorSchema, 404: errorSchema, 422: errorSchema },
+  };
+  app.put('/orders/:id/items', { schema: editItemsSchema }, async (request, reply) => {
+    const user = await deps.authenticate(request);
+    requireRole(user, 'admin');
+    const { id } = parseJson(orderIdParamSchema, request.params);
+    const body = parseJson(
+      z.object({
+        items: z
+          .array(
+            z.object({
+              variantId: z.uuid(),
+              quantity: z.number().int().positive().max(999),
+            }),
+          )
+          .min(1),
+      }),
+      request.body,
+    );
+
+    const existing = await service.getOrderAdmin(id);
+    if (!existing) throw new AppError(404, 'ORDER_NOT_FOUND', 'Order not found');
+
+    // Consolidar cantidades por variante.
+    const byVariant = new Map<string, number>();
+    for (const item of body.items) {
+      byVariant.set(item.variantId, (byVariant.get(item.variantId) ?? 0) + item.quantity);
+    }
+    const variantIds = [...byVariant.keys()];
+
+    // Resolver datos de catálogo y precio vigente de cada variante.
+    const variantResult = await deps.pool.query<{
+      variant_id: string;
+      sku: string;
+      ean: string | null;
+      product_id: string;
+      product_name: string;
+      net_unit_amount_cents: number | null;
+      vat_rate: string | null;
+    }>(
+      `SELECT v.id AS variant_id, v.sku, v.ean, v.product_id, p.name AS product_name,
+              pr.net_unit_amount_cents, pr.vat_rate
+       FROM catalog_product_variants v
+       JOIN catalog_products p ON p.id = v.product_id
+       LEFT JOIN pricing_variant_prices pr ON pr.variant_id = v.id
+       WHERE v.id = ANY($1::uuid[])`,
+      [variantIds],
+    );
+    const found = new Map(variantResult.rows.map((row) => [row.variant_id, row]));
+    for (const variantId of variantIds) {
+      if (!found.has(variantId)) {
+        throw new AppError(422, 'VARIANT_NOT_FOUND', `La variante ${variantId.slice(0, 8)} no existe en el catálogo`);
+      }
+      const row = found.get(variantId);
+      if (row?.net_unit_amount_cents == null) {
+        throw new AppError(422, 'PRICE_MISSING', `Falta el precio de la variante ${row?.sku ?? variantId.slice(0, 8)}`);
+      }
+    }
+
+    const VAT_POINTS: Record<string, number> = { general: 2100, reduced: 1000, 'super-reduced': 400 };
+    const itemInputs = variantIds.map((variantId) => {
+      const row = found.get(variantId)!;
+      const quantity = byVariant.get(variantId)!;
+      const unitPriceCents = row.net_unit_amount_cents!;
+      const points = VAT_POINTS[row.vat_rate ?? 'general'] ?? 2100;
+      const taxCents = Math.round((unitPriceCents * quantity * points) / 10_000);
+      return {
+        productId: row.product_id,
+        variantId,
+        sku: row.sku,
+        ean: row.ean,
+        name: row.product_name,
+        unitPriceCents,
+        discountCents: 0,
+        taxCents,
+        quantity,
+      };
+    });
+
+    const netSubtotalCents = itemInputs.reduce((acc, item) => acc + item.unitPriceCents * item.quantity, 0);
+    const taxCents = itemInputs.reduce((acc, item) => acc + item.taxCents, 0);
+    const subtotalCents = netSubtotalCents + taxCents;
+    const discountCents = Math.min(existing.discountCents, subtotalCents);
+    // El coste de envío original se conserva: total - (subtotal - descuento).
+    const shippingCents = Math.max(0, existing.totalCents - Math.max(0, existing.subtotalCents - existing.discountCents));
+    const totalCents = Math.max(0, subtotalCents - discountCents) + shippingCents;
+
+    try {
+      const updated = await service.editItems(id, itemInputs, {
+        subtotalCents,
+        discountCents,
+        taxCents,
+        totalCents,
+      });
+      return reply.send(serializeOrder(updated));
+    } catch (error) {
+      throw mapOrderError(error);
+    }
+  });
 }

 function mapOrderError(error: unknown): Error {
@@ -263,6 +407,7 @@ function serializeOrder(order: {
  discountCents: number;
  taxCents: number;
  totalCents: number;
+  trackingNumber?: string | null;
  createdAt: Date;
  updatedAt: Date;
  idempotencyKey: string | null;
@@ -290,6 +435,7 @@ function serializeOrder(order: {
    discountCents: order.discountCents,
    taxCents: order.taxCents,
    totalCents: order.totalCents,
+    trackingNumber: order.trackingNumber ?? null,
    idempotencyKey: order.idempotencyKey,
    items: order.items.map((item) => ({
      id: item.id,
--- a/project/src/modules/orders/application/order-service.ts
+++ b/project/src/modules/orders/application/order-service.ts
@@ -5,7 +5,7 @@ import type {
  OrderServicePort,
  CreateOrderCommand,
 } from '../domain/ports.js';
-import { isTransitionAllowed, type OrderState, type OrderView } from '../domain/order.js';
+import { isTransitionAllowed, type OrderState, type OrderView, type OrderItemInput } from '../domain/order.js';

 export class OrderService implements OrderServicePort {
  constructor(
@@ -39,6 +39,20 @@ export class OrderService implements OrderServicePort {
    return this.repo.search(filters);
  }

+  /** Edición admin: reemplaza artículos y totales del pedido. */
+  async editItems(
+    id: string,
+    items: OrderItemInput[],
+    totals: { subtotalCents: number; discountCents: number; taxCents: number; totalCents: number },
+  ): Promise<OrderView> {
+    const existing = await this.repo.findById(id);
+    if (!existing) throw new OrderNotFoundError();
+    if (!this.repo.replaceItems) throw new Error('Order repository does not support item editing');
+    const updated = await this.repo.replaceItems(id, items, totals);
+    if (!updated) throw new OrderNotFoundError();
+    return updated;
+  }
+
  async transition(id: string, next: OrderState, userId: string): Promise<OrderView> {
    const existing = await this.repo.findByIdAndUserId(id, userId);
    if (!existing) throw new OrderNotFoundError();
@@ -60,12 +74,12 @@ export class OrderService implements OrderServicePort {
    return this.repo.findById(id);
  }

-  async transitionAdmin(id: string, next: OrderState): Promise<OrderView> {
+  async transitionAdmin(id: string, next: OrderState, trackingNumber?: string): Promise<OrderView> {
    const existing = await this.repo.findById(id);
    if (!existing) throw new OrderNotFoundError();
    if (!isTransitionAllowed(existing.state, next))
      throw new OrderStateTransitionError(existing.state, next);
-    const updated = await this.repo.updateState(id, next);
+    const updated = await this.repo.updateState(id, next, trackingNumber);
    if (!updated) throw new OrderNotFoundError();
    if (next === 'PAID')
      await this.events.emit({ type: 'OrderPaid', orderId: id, userId: existing.userId });
--- a/project/src/modules/orders/domain/order.ts
+++ b/project/src/modules/orders/domain/order.ts
@@ -37,6 +37,7 @@ export interface Order {
  discountCents: number;
  taxCents: number;
  totalCents: number;
+  trackingNumber?: string | null;
  createdAt: Date;
  updatedAt: Date;
 }
--- a/project/src/modules/orders/domain/ports.ts
+++ b/project/src/modules/orders/domain/ports.ts
@@ -16,7 +16,13 @@ export interface OrderRepository {
  }): Promise<{ items: OrderView[]; total: number }>;
  findById(id: string): Promise<OrderView | undefined>;
  findByIdAndUserId(id: string, userId: string): Promise<OrderView | undefined>;
-  updateState(id: string, state: OrderState): Promise<OrderView | undefined>;
+  updateState(id: string, state: OrderState, trackingNumber?: string): Promise<OrderView | undefined>;
+  /** Reemplaza los artículos y totales del pedido (edición admin). */
+  replaceItems?(
+    id: string,
+    items: OrderItemInput[],
+    totals: { subtotalCents: number; discountCents: number; taxCents: number; totalCents: number },
+  ): Promise<OrderView | undefined>;
 }

 export interface OrderEventPublisher {
@@ -38,7 +44,7 @@ export interface OrderServicePort {
    offset: number;
  }): Promise<{ items: OrderView[]; total: number }>;
  transition(id: string, next: OrderState, userId: string): Promise<OrderView>;
-  transitionAdmin(id: string, next: OrderState): Promise<OrderView>;
+  transitionAdmin(id: string, next: OrderState, trackingNumber?: string): Promise<OrderView>;
  getOrder(id: string, userId: string): Promise<OrderView | undefined>;
  getOrderAdmin(id: string): Promise<OrderView | undefined>;
 }
--- a/project/src/modules/orders/infrastructure/order-status-mailer.ts
+++ b/project/src/modules/orders/infrastructure/order-status-mailer.ts
@@ -0,0 +1,100 @@
+import nodemailer from 'nodemailer';
+import type pg from 'pg';
+
+const SMTP_KEYS = ['smtp_host', 'smtp_port', 'smtp_secure', 'smtp_user', 'smtp_pass', 'smtp_from'] as const;
+
+export const ORDER_STATE_LABELS: Record<string, string> = {
+  PENDING: 'Pendiente',
+  AWAITING_PAYMENT: 'Esperando pago',
+  PAID: 'Pagado',
+  PROCESSING: 'En preparación',
+  SHIPPED: 'Enviado',
+  DELIVERED: 'Entregado',
+  CANCELLED: 'Cancelado',
+  REFUNDED: 'Reembolsado',
+  PARTIALLY_REFUNDED: 'Reembolso parcial',
+};
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => ({
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+  })[character] ?? character);
+}
+
+export interface OrderStatusNotificationInput {
+  to: string;
+  orderId: string;
+  state: string;
+  trackingNumber?: string | null;
+}
+
+/**
+ * Sends order status change emails through the SMTP configuration stored in
+ * store_settings (Ajustes → SMTP / Email), with env fallback. Failures are
+ * thrown so callers can report `notified: false` without breaking the flow.
+ */
+export async function sendOrderStatusEmail(
+  pool: pg.Pool,
+  input: OrderStatusNotificationInput,
+): Promise<void> {
+  const result = await pool.query<{ key: string; value: string }>(
+    `SELECT key, value FROM store_settings WHERE key = ANY($1::text[])`,
+    [SMTP_KEYS],
+  );
+  const settings = Object.fromEntries(result.rows.map((row) => [row.key, row.value]));
+  const host = settings.smtp_host?.trim() || process.env.SMTP_HOST?.trim();
+  const user = settings.smtp_user?.trim() || process.env.SMTP_USER?.trim();
+  const password = settings.smtp_pass || process.env.SMTP_PASS;
+  const from = settings.smtp_from?.trim() || process.env.SMTP_FROM?.trim() || user;
+  if (!host || !user || !password || !from) {
+    throw new Error('SMTP is not configured in Ajustes → SMTP / Email');
+  }
+  const port = Number(settings.smtp_port || process.env.SMTP_PORT || '465');
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('SMTP port is invalid in Ajustes → SMTP / Email');
+  }
+
+  const transporter = nodemailer.createTransport({
+    host,
+    port,
+    secure: (settings.smtp_secure ?? process.env.SMTP_SECURE) !== 'false' || port === 465,
+    auth: { user, pass: password },
+  });
+
+  const shortId = input.orderId.slice(0, 8);
+  const stateLabel = ORDER_STATE_LABELS[input.state] ?? input.state;
+  const trackingLine = input.trackingNumber
+    ? `Número de seguimiento: ${input.trackingNumber}`
+    : '';
+
+  await transporter.sendMail({
+    from,
+    to: input.to,
+    subject: `Tu pedido #${shortId} ahora está: ${stateLabel} — Mercado de Vida`,
+    text: [
+      `Hola,`,
+      '',
+      `Tu pedido #${shortId} ha cambiado de estado: ${stateLabel}.`,
+      trackingLine,
+      '',
+      'Puedes consultar el detalle desde tu cuenta en mercadodevida.',
+      '',
+      'Gracias por tu compra.',
+    ]
+      .filter((line) => line !== '')
+      .join('\n'),
+    html: [
+      `<p>Hola,</p>`,
+      `<p>Tu pedido <strong>#${escapeHtml(shortId)}</strong> ha cambiado de estado: <strong>${escapeHtml(stateLabel)}</strong>.</p>`,
+      trackingLine ? `<p>Número de seguimiento: <strong>${escapeHtml(input.trackingNumber ?? '')}</strong></p>` : '',
+      `<p>Puedes consultar el detalle desde tu cuenta en mercadodevida.</p>`,
+      `<p>Gracias por tu compra.</p>`,
+    ]
+      .filter((line) => line !== '')
+      .join(''),
+  });
+}
--- a/project/src/modules/orders/infrastructure/pg-order-repository.ts
+++ b/project/src/modules/orders/infrastructure/pg-order-repository.ts
@@ -12,6 +12,7 @@ interface OrderRow {
  discount_cents: number;
  tax_cents: number;
  total_cents: number;
+  tracking_number: string | null;
  created_at: Date;
  updated_at: Date;
 }
@@ -177,19 +178,62 @@ export class PgOrderRepository implements OrderRepository {
    return { ...toOrder(order), items: items.rows.map(toItem) };
  }

-  async updateState(id: string, state: OrderState): Promise<OrderView | undefined> {
+  async updateState(id: string, state: OrderState, trackingNumber?: string): Promise<OrderView | undefined> {
    const result = await this.pool.query<OrderRow>(
-      `UPDATE orders_orders SET state = $2, updated_at = now()
+      `UPDATE orders_orders SET state = $2, tracking_number = COALESCE($3, tracking_number), updated_at = now()
       WHERE id = $1 RETURNING *`,
-      [id, state],
+      [id, state, trackingNumber ?? null],
    );
    const order = result.rows[0];
    if (!order) return undefined;
-    const items = await this.pool.query<ItemRow>(
-      'SELECT * FROM orders_items WHERE order_id = $1 ORDER BY created_at, id',
-      [id],
-    );
-    return { ...toOrder(order), items: items.rows.map(toItem) };
+    return this.findById(order.id);
+  }
+
+  async replaceItems(
+    id: string,
+    items: OrderItemInput[],
+    totals: { subtotalCents: number; discountCents: number; taxCents: number; totalCents: number },
+  ): Promise<OrderView | undefined> {
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN');
+      const orderResult = await client.query<OrderRow>(
+        `UPDATE orders_orders
+         SET subtotal_cents = $2, discount_cents = $3, tax_cents = $4, total_cents = $5, updated_at = now()
+         WHERE id = $1 RETURNING *`,
+        [id, totals.subtotalCents, totals.discountCents, totals.taxCents, totals.totalCents],
+      );
+      if (!orderResult.rows[0]) {
+        await client.query('ROLLBACK');
+        return undefined;
+      }
+      await client.query('DELETE FROM orders_items WHERE order_id = $1', [id]);
+      for (const item of items) {
+        await client.query<ItemRow>(
+          `INSERT INTO orders_items (order_id, product_id, variant_id, sku, ean, name, unit_price_cents, discount_cents, tax_cents, quantity)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+          [
+            id,
+            item.productId,
+            item.variantId,
+            item.sku,
+            item.ean,
+            item.name,
+            item.unitPriceCents,
+            item.discountCents,
+            item.taxCents,
+            item.quantity,
+          ],
+        );
+      }
+      await client.query('COMMIT');
+      return this.findById(id);
+    } catch (error) {
+      await client.query('ROLLBACK');
+      throw error;
+    } finally {
+      client.release();
+    }
  }
 }

@@ -204,6 +248,7 @@ function toOrder(row: OrderRow): Order {
    discountCents: row.discount_cents,
    taxCents: row.tax_cents,
    totalCents: row.total_cents,
+    trackingNumber: row.tracking_number,
    createdAt: row.created_at,
    updatedAt: row.updated_at,
  };