michangarrito/docs/01-epicas/MCH-028-marketplace-proveedores.md

---
id: EPIC-MCH-028
type: Epic
title: "MCH-028: Marketplace de Proveedores"
code: MCH-028
status: Completado
phase: 7
priority: P3
created_at: 2026-01-10
updated_at: 2026-01-10
simco_version: "3.8.0"
dependencies:
  blocks: []
  depends_on: []
---

# MCH-028: Marketplace de Proveedores

## Metadata
- **Codigo:** MCH-028
- **Fase:** 7 - Expansion (Futuro)
- **Prioridad:** P3
- **Estado:** Completado
- **Fecha estimada:** Sprint 20+

## Descripcion

Marketplace B2B que conecta micro-negocios con distribuidores y mayoristas: catalogo de proveedores, pedidos directos, comparacion de precios, y entregas coordinadas.

## Objetivos

1. Directorio de proveedores verificados
2. Catalogos de productos mayoreo
3. Pedidos B2B desde la app
4. Comparacion de precios
5. Tracking de pedidos a proveedor

## Alcance

### Incluido
- Directorio de distribuidores por zona
- Catalogo de productos de mayoreo
- Sistema de pedidos B2B
- Comparador de precios
- Historial de compras

### Excluido
- Pagos procesados por MiChangarrito
- Logistica propia
- Credito a negocios (lo da el proveedor)
- Exclusividad con proveedores

## Modelo de Negocio

### Para Tienditas
- Acceso gratuito al directorio
- Pedidos mas faciles
- Mejores precios por volumen
- Menos tiempo buscando proveedor

### Para Proveedores
- Acceso a base de clientes
- Comision por pedido (3-5%)
- Dashboard de ventas
- Promociones destacadas

### Revenue para MiChangarrito
- Comision por pedido confirmado
- Listados destacados (premium)
- Datos de mercado (anonimizados)

## Flujos de Usuario

### Tiendita Busca Proveedor
```
1. Dueno abre "Proveedores"
2. Filtra por categoria (bebidas, botanas)
3. Ve lista de proveedores en su zona
4. Compara precios de Coca-Cola
5. Selecciona proveedor con mejor precio
6. Hace pedido desde la app
7. Proveedor confirma y entrega
```

### Proveedor Recibe Pedido
```
1. Proveedor recibe notificacion
2. Ve pedido en su dashboard:
   - Tienda: "Tiendita Don Jose"
   - Productos: 10 cajas Coca-Cola
   - Direccion: Calle X #123
3. Confirma disponibilidad
4. Programa entrega
5. Tienda recibe notificacion
```

## Modelo de Datos

### Tablas (schema: marketplace)

**suppliers**
- id, name, legal_name, rfc
- categories, coverage_zones
- contact_phone, contact_email
- logo_url, verified, rating
- status

**supplier_products**
- id, supplier_id, name, sku
- category, price_unit, min_order
- image_url, barcode, active

**supplier_orders**
- id, tenant_id, supplier_id
- status, subtotal, total
- delivery_address, delivery_date
- notes, created_at

**supplier_order_items**
- id, order_id, product_id
- quantity, unit_price, total

**supplier_reviews**
- id, tenant_id, supplier_id
- rating, comment, created_at

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /marketplace/suppliers | Listar proveedores |
| GET | /marketplace/suppliers/:id | Detalle proveedor |
| GET | /marketplace/suppliers/:id/products | Productos |
| POST | /marketplace/orders | Crear pedido |
| GET | /marketplace/orders | Mis pedidos |
| PUT | /marketplace/orders/:id/status | Actualizar estado |
| POST | /marketplace/reviews | Dejar resena |

## UI Components

### SupplierDirectory
- Lista de proveedores
- Filtros por categoria, zona
- Rating y resenas
- Productos destacados

### SupplierProfile
- Info del proveedor
- Catalogo de productos
- Precios y minimos
- Boton "Hacer pedido"

### SupplierOrderForm
- Seleccion de productos
- Cantidades
- Direccion de entrega
- Fecha preferida
- Notas

### OrderTracking
- Estado del pedido
- Fecha estimada
- Contacto del proveedor

## Proveedores Iniciales (Mexico)

### Categorias Prioritarias
1. **Bebidas:** Coca-Cola FEMSA, Pepsi, distribuidores locales
2. **Botanas:** Sabritas, Barcel
3. **Pan:** Bimbo, Grupo Bimbo
4. **Lacteos:** Lala, Alpura, distribuidores
5. **Abarrotes:** Mayoristas locales

### Onboarding de Proveedores
```
1. Proveedor se registra
2. Verifica RFC y datos fiscales
3. Sube catalogo de productos
4. Define zonas de cobertura
5. Configura minimos de pedido
6. Queda visible para tiendas
```

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| DB Schema | Completado | `database/schemas/16-marketplace.sql` |
| marketplace.module | Completado | `modules/marketplace/` |
| Entities | Completado | `modules/marketplace/entities/` |
| Service | Completado | `modules/marketplace/marketplace.service.ts` |
| Controller | Completado | `modules/marketplace/marketplace.controller.ts` |
| Supplier portal | Pendiente | App separada o seccion |
| SupplierDirectory UI | Completado | `pages/Marketplace.tsx` |

## Dependencias

### Depende de
- MCH-003 (Productos - para matching)
- MCH-009 (Predicciones - sugerencias)
- Base de usuarios activos

### Bloquea a
- Ninguno

## Criterios de Aceptacion

- [ ] Proveedores pueden registrarse
- [ ] Tiendas pueden buscar proveedores
- [ ] Pedidos B2B funcionan
- [ ] Tracking de pedidos funciona
- [ ] Reviews funcionan
- [ ] Comisiones se calculan

## Metricas de Exito

| Metrica | Objetivo Inicial |
|---------|------------------|
| Proveedores registrados | 50 en zona metro |
| Pedidos mensuales | 100 |
| GMV mensual | $500,000 MXN |
| NPS proveedores | >50 |

## Riesgos

| Riesgo | Mitigacion |
|--------|------------|
| Proveedores no se registran | Onboarding personalizado |
| Calidad de servicio variable | Sistema de reviews |
| Precios no competitivos | Comparador visible |
| Entregas fallidas | Penalizacion a proveedor |

## Roadmap Interno

1. **MVP:** Directorio + pedidos manuales
2. **V2:** Pedidos automaticos desde inventario bajo
3. **V3:** Rutas optimizadas para proveedores
4. **V4:** Credito B2B (factoraje)

---

**Ultima actualizacion:** 2026-01-10