Glosario

Para mantener consistencia entre código, UI, emails y conversaciones internas.

Producto / dominio

Listing Una publicación de un vendedor. Tiene un kind (card, accessory, bulk, sealed). En español user-facing decimos “publicación”. En código siempre “listing”.

Kind Tipo de listing. Discriminated union: card | accessory | bulk | sealed. Cada uno tiene campos distintos.

Card Una carta individual. El listing kind: card referencia una cardId del catálogo.

Accessory Producto relacionado pero no es una carta: deckbox, playmat, sleeves, dados, etc. En UI “accesorio”.

Bulk (también “Challa”) Un lote de cartas a granel — el vendedor describe la composición (commons / uncommons / mixto), no las cartas individuales. En UI usamos “challa” (jerga local).

Sealed Producto sellado: ETBs, sobres, booster boxes, decks construidos. En UI “sellado”.

TCG Trading Card Game. Slug: pokemon, one-piece, magic, yugioh, digimon. Multi-TCG desde el día uno.

Set Una colección dentro de un TCG. Por ejemplo, “Scarlet & Violet 151” es un set de Pokémon. Identificado por {tcg}-{slug}.

Variant Variante de impresión de una carta. Para Pokémon: Holo Foil, Reverse Holo, etc.

Condition Estado físico de la carta. Para card: NM (Near Mint), LP (Lightly Played), MP (Moderately Played), HP (Heavily Played), DAM (Damaged). Para accessory: Nuevo/Usado. Para bulk: label descriptivo libre.

Stock Cantidad disponible en un listing (listing.quantity). Al hacer checkout, se descuenta. Si la orden se cancela, se restaura.

Órdenes y compras

Order La instancia de una compra. Vive en la colección orders.

displayId ID corto del formato XXXX-XXXX (8 chars + dash). Visible para el usuario. Distinto del _id interno order-{nanoid}.

Status de orden

• awaiting_payment — orden creada, esperando confirmación de pago de MP.
• pending — pago confirmado, esperando que el vendedor acepte.
• accepted — vendedor aceptó, está preparando el envío.
• shipped — vendedor marcó como enviado.
• completed — comprador confirmó recepción (o auto-completada después de 14 días).
• canceled — cancelada (por buyer, seller, system o admin).

Snapshot (de orden) Cuando se crea una orden, se guardan los datos del listing en order.items[].snapshot (baseName, setName, condition, etc.). Esto evita que cambios posteriores en el listing afecten la orden histórica.

Comisión Lo que se queda tcgcards. Sale del total bruto pagado por el comprador, se descuenta cuando la orden se completa y el resto va al wallet del vendedor.

Wallet y pagos

Wallet Cuenta interna del usuario en CLP cents. Vive como user.walletBalance (denormalizado para queries rápidas) + tabla wallet_entries (ledger inmutable de movimientos).

Wallet entry Una transacción individual en el ledger. Tipos: crédito por venta, débito por retiro, devolución, etc.

Withdrawal Solicitud del usuario para sacar dinero del wallet a su cuenta bancaria. Procesada manualmente por el admin.

System wallet El wallet del owner del marketplace (cuenta isSystem: true). Acumula las comisiones.

Owner draw Cuando el admin saca dinero del system wallet para uso personal/empresarial.

Reconciliación Comparar el walletBalance denormalizado de cada user contra la suma del ledger de wallet_entries. Cron diario (wallet-reconcile-daily).

Pagos externos

MP = Mercado Pago. Único procesador.

Preference Lo que se crea en MP al iniciar checkout. URL init_point redirige al usuario para pagar.

Webhook Notificación entrante de MP a tcgcards-api cuando un payment cambia de estado. Endpoint /api/v1/webhooks/mp.

Late refund Cuando el comprador paga pero la orden ya expiró (timeout pasó). Iniciamos refund automático a la tarjeta original.

Disputas y moderación

Dispute El comprador o vendedor abre una disputa cuando hay un problema. Razones: not_received, damaged, incorrect, counterfeit, no_response, other. Una dispute por orden.

Response La contraparte responde a la disputa con su versión.

Outcome La resolución del admin: canceled_in_favor_of_buyer, closed_in_favor_of_seller, dismissed.

Report Denuncia de un usuario a un listing o a otro user. No es disputa.

Status de user (moderation) active, warned, suspended, banned. Después de un warning, si el comportamiento persiste, se suspende; si grave, se banea.

Auth y permisos

Sesión Cookie firmada por Auth.js. Contiene userId, username, isAdmin.

JWT interno Token HS256 que el frontend manda al backend en server actions. Firmado con INTERNAL_JWT_SECRET (compartido por ambos repos).

Internal auth Header X-Internal-Auth: <secret> para autenticar server actions de Next.js → API. Usa INTERNAL_AUTH_SECRET.

Internal cron Header X-Internal-Cron-Secret: <secret> para autenticar Cloud Scheduler → API. Usa INTERNAL_CRON_SECRET.

Admin User con isAdmin: true en Mongo. Hoy se setea manualmente (ver runbook).

Otros

Cron job o scheduled task Tarea programada que corre periódicamente. En tcgcards corren en Cloud Scheduler. Ver crons.

Backfill Script one-shot para actualizar data histórica después de un cambio de schema. Viven en tcgcards-api/scripts/backfill-*.ts.

Sync Sincronización del catálogo (cards + sets) desde TCGplayer. Scripts sync:initial (rebuild completo) y sync:incremental (cambios).

Catalog El conjunto de cards + sets de los TCGs soportados. Sincronizado desde TCGplayer.

TCGplayer La fuente de verdad del catálogo (precios USD, imágenes, metadata). No es nuestro upstream comercial, solo de datos.

Edge function (Vercel) Función que corre en el edge de Vercel. No usamos — todo lo nuestro es server components.

Server Action Función 'use server' de Next.js que se ejecuta en el servidor pero se llama desde un client component como si fuera local. Reemplaza API routes para mutations.

Server Component Componente React que se renderiza en server, no envía JS al client. Default en App Router de Next.js 16.

RSC = React Server Component. Sinónimo.

Hydration mismatch Error de Next.js cuando lo que renderiza el server difiere de lo que renderiza el client en el primer render. Casos comunes: leer cookies/preferencias del user (theme, locale). Fix: mounted flag.

Discriminated union (TS) Tipo unión donde cada variante tiene un campo discriminante. En tcgcards: Listing discrimina por kind. TS estrechá el tipo según el valor del discriminante.

Exhaustive switch Switch que cubre todos los valores posibles de una discriminated union. Se garantiza con default: const _exhaustive: never — si agregas un valor nuevo y no actualizas el switch, TS te avisa con un error.