← volver a /proyectos ← back to /proyectos
fullstack YANCARLOSOFICIAL/Tienda-de-celulares-ecommerce-

Tienda Cell

E-commerce de celulares en monorepo: frontend Vue 3, backend FastAPI con PostgreSQL, carrito, panel admin y facturación electrónica ante la DIAN.

Phone store e-commerce built as a monorepo: Vue 3 frontend, FastAPI backend with PostgreSQL, cart, admin panel and electronic invoicing.

Vue 3TypeScriptFastAPIPostgreSQLDockerJWT
terminal — clonar

$ git clone https://github.com/YANCARLOSOFICIAL/Tienda-de-celulares-ecommerce-.git

$ cd Tienda-de-celulares-ecommerce-


  • Monorepo con docker-compose: frontend, API y base de datos se levantan con un solo comando.
  • Flujo de compra completo: catálogo con filtros multiselección, búsqueda predictiva, carrito y checkout en 3 pasos con envío gratis por umbral.
  • Panel de administración: productos (con galería), categorías y pedidos.
  • Facturación electrónica real: precios en COP y facturas ante la DIAN a través de Factus.
  • Backend con estándares: SQLAlchemy 2 + Alembic (migraciones), Pydantic v2, JWT + bcrypt, Pytest y API documentada con Swagger/Redoc.
Descargado del repositorio en cada build. Downloaded from the repository on every build.

Tienda Cell

Tienda Cell es un e-commerce de celulares desarrollado como un monorepo con un frontend en Vue 3 + Vite + TypeScript y un backend en FastAPI con PostgreSQL. El proyecto incluye una tienda pública, autenticación de usuarios, carrito de compras, gestión de pedidos y un panel de administración para administrar productos, categorías y órdenes.

La tienda opera en Colombia: los precios se muestran en pesos colombianos (COP, sin decimales) y la facturación electrónica se emite ante la DIAN a través de Factus. Los datos de país, moneda, contacto, ubicación y reglas de envío están centralizados en frontend/src/config/site.ts.

Características principales

  • Catálogo de productos con filtros multiselección (marca y categoría), galería de imágenes por producto y búsqueda predictiva.
  • Registro e inicio de sesión de usuarios con autenticación JWT.
  • Carrito de compras y flujo de pedidos (checkout de 3 pasos con envío gratis por umbral).
  • Notificaciones (toasts) para las acciones del cliente y página 404 dedicada.
  • Panel de administración para gestionar:
    • productos (incluida la galería de imágenes)
    • categorías
    • pedidos
  • API REST documentada con Swagger / Redoc.
  • Migraciones de base de datos con Alembic.
  • Datos de ejemplo mediante seed para desarrollo.
  • Rutas del frontend con carga diferida (code-splitting).

Stack tecnológico

Frontend

  • Vue 3
  • Vite
  • TypeScript
  • Pinia
  • Vue Router
  • Tailwind-inspired styling y componentes reutilizables

Backend

  • Python 3.12+
  • FastAPI
  • SQLAlchemy 2.x
  • PostgreSQL
  • Alembic
  • Pydantic v2
  • JWT + bcrypt
  • Pytest

Estructura del proyecto

.
├── docker-compose.yml       # Stack de desarrollo (db + api) — se corre desde la raíz
├── .env.example             # Overrides opcionales del compose (puertos, credenciales DB)
├── backend/                 # API FastAPI y base de datos
│   ├── app/                 # Aplicación principal
│   │   ├── core/            # Configuración, seguridad y excepciones
│   │   ├── db/              # Conexión y modelos base
│   │   ├── models/          # Modelos SQLAlchemy
│   │   ├── routers/         # Endpoints HTTP
│   │   ├── schemas/         # Schemas Pydantic
│   │   ├── services/        # Lógica de negocio
│   │   └── utils/           # Utilidades
│   ├── alembic/             # Migraciones
│   ├── scripts/             # Seed y scripts auxiliares
│   ├── tests/               # Pruebas del backend
│   ├── Dockerfile           # Imagen Docker del backend
│   ├── docker-entrypoint.sh # Migraciones + seed + uvicorn (idempotente)
│   └── pyproject.toml       # Dependencias y configuración Python
├── frontend/                # Aplicación Vue 3 + Vite + TypeScript
│   ├── index.html
│   ├── package.json         # Scripts y dependencias del frontend
│   ├── vite.config.ts       # Configuración de Vite (incluye alias `@` → `src/`)
│   ├── public/              # Archivos estáticos
│   └── src/
│       ├── api/             # Clientes HTTP del backend (uno por dominio)
│       ├── stores/          # Estado global con Pinia (uno por dominio)
│       ├── composables/     # Composables reutilizables
│       ├── components/      # Componentes agrupados por dominio/rol
│       │   ├── layout/      # Navbar, Footer, WhatsAppButton, BackToTop
│       │   ├── home/        # Secciones de la landing (Hero, Featured, etc.)
│       │   ├── product/     # ProductCard, ProductGallery, ProductReviews, ...
│       │   ├── search/      # PredictiveSearch
│       │   ├── compare/     # CompareBar
│       │   ├── contact/     # ContactForm, MapLocation
│       │   └── admin/       # Componentes del panel de administración
│       ├── pages/           # Vistas enrutadas
│       └── router/          # Configuración de rutas
└── docs/                    # Documentación adicional

Requisitos previos

Antes de comenzar, asegúrate de tener instalado:

  • Node.js 20+ y npm
  • Python 3.12+
  • PostgreSQL (si vas a correr la base de datos localmente)
  • Docker y Docker Compose (opcional, para ejecutar el backend en contenedores)

Instalación y ejecución

1. Clonar el repositorio

git clone <url-del-repositorio>
cd tienda-cell

2. Configurar el backend

cd backend
cp .env.example .env

Ajusta las variables de entorno en el archivo .env si es necesario. Por defecto se apunta a una base de datos PostgreSQL local en localhost:5433.

Instala las dependencias del backend con uv:

uv sync

Aplica las migraciones y carga los datos de ejemplo:

uv run alembic upgrade head
uv run python scripts/seed.py

Inicia el backend:

uv run uvicorn app.main:app --reload

La API estará disponible en:

3. Configurar el frontend

En una nueva terminal, desde la raíz del repositorio:

cd frontend
npm install
npm run dev

La aplicación frontend correrá en:

Ejecución con Docker

El backend y la base de datos se levantan con Docker Compose desde la raíz del repositorio:

docker compose build      # solo la primera vez, o al cambiar backend/requirements.txt
docker compose up -d

Con eso queda todo listo:

  • La API aplica migraciones y el seed automáticamente al arrancar (idempotente).
  • restart: unless-stopped vuelve a levantar los contenedores cuando reinicia Docker Desktop o la máquina — ya no hay que hacer up cada vez que se reabre el proyecto.
  • El código de backend/app está montado en vivo con recarga automática de uvicorn: editar y guardar basta, sin reconstruir la imagen.

Comandos útiles:

docker compose ps           # estado y salud de los servicios
docker compose logs -f api  # logs de la API
docker compose stop         # detener sin borrar
docker compose down         # detener y eliminar contenedores (los datos persisten en el volumen)
docker compose down -v      # además borra la base de datos

El frontend se sigue corriendo aparte con cd frontend && npm run dev (Vite hace proxy de /api y /health hacia http://localhost:8001). Puertos y credenciales de la DB se pueden ajustar copiando .env.example a .env en la raíz.

Pruebas

Backend

cd backend
uv run pytest

Frontend

cd frontend
npm run build   # typecheck (tsc) + build de producción

Credenciales de desarrollo

El seed genera usuarios de prueba para desarrollo. Por defecto:

  • Administrador: admin@tiendacell.com / Admin123!
  • Usuario estándar: usuario@tiendacell.com / Usuario123!

Estas credenciales solo deben usarse en entornos de desarrollo.

Variables de entorno importantes

En el archivo .env del backend puedes ajustar:

  • DATABASE_URL: conexión a PostgreSQL
  • SECRET_KEY: clave secreta para JWT
  • ACCESS_TOKEN_EXPIRE_MINUTES: duración del token
  • CORS_ORIGINS: orígenes permitidos por CORS
  • SEED_ADMIN_EMAIL, SEED_ADMIN_PASSWORD, SEED_USER_EMAIL, SEED_USER_PASSWORD

Facturación electrónica con Factus

El backend se integra con Factus para emitir facturas electrónicas validadas ante la DIAN.

Configuración

Copia las variables de .env.example y completa las credenciales que entrega Factus:

FACTUS_BASE_URL=https://api-sandbox.factus.com.co   # sandbox para pruebas
FACTUS_CLIENT_ID=tu-client-id
FACTUS_CLIENT_SECRET=tu-client-secret
FACTUS_USERNAME=tu-correo
FACTUS_PASSWORD=tu-password
FACTUS_NUMBERING_RANGE_ID=          # opcional si tienes un solo rango activo
FACTUS_DEFAULT_TAX_RATE=19.00       # IVA por defecto de los productos

Si estas variables no están definidas, la facturación queda deshabilitada (error 503) y el resto de la tienda funciona normalmente.

Cómo funciona

Versión de la API: FACTUS_API_VERSION (por defecto v2). La V2 usa códigos DIAN (identification_document_code, unit_measure_code...), precios sin IVA y payment_details; la integración convierte automáticamente los precios con IVA de la tienda a base gravable y ajusta el total al que calcula Factus (con reintento automático si hay desajuste por centavos).

  1. Autenticación OAuth2: el servicio solicita el token a POST /oauth/token (grant password) y lo renueva automáticamente con el grant refresh_token cuando expira (~1 hora).
  2. Emisión: cada pedido se convierte al payload de POST /v1/bills/validate:
    • reference_code = order-{id} (idempotente: no se emiten facturas duplicadas).
    • El envío se agrega como línea exenta de IVA.
    • El cupón se reporta como descuento a nivel de factura (allowance_charges).
    • Los datos del adquiriente (identificación, tipo de documento, etc.) se envían por API al momento de facturar.
  3. Persistencia: el resultado (CUFE, número, estado DIAN, respuesta cruda) se guarda en la tabla invoices.
  4. Descargas: Factus devuelve PDF/XML en Base64 dentro del JSON; el backend los decodifica y sirve como archivos.

Endpoints (/api/invoices)

Método Ruta Permisos Descripción
POST /orders/{order_id} Admin Emite y valida la factura electrónica del pedido
GET /orders/{order_id} Dueño o Admin Consulta la factura de un pedido
DELETE /orders/{order_id} Dueño o Admin Elimina una factura NO validada por la DIAN
GET /{bill_number}/pdf Dueño o Admin Descarga el PDF de la representación gráfica
GET /{bill_number}/xml Dueño o Admin Descarga el XML UBL
GET /numbering-ranges Admin Lista los rangos de numeración activos en Factus

Ejemplo de emisión:

curl -X POST http://localhost:8000/api/invoices/orders/1 \
  -H "Authorization: Bearer <token-admin>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "identification": "1020304050",
      "names": "Juan Pérez",
      "email": "juan@example.com"
    }
  }'

Nota producción: cambia FACTUS_BASE_URL a https://api.factus.com.co. Para anular una factura ya validada por la DIAN se debe emitir una nota crédito (aún no implementado).

Integración en el frontend

  • frontend/src/api/invoices.ts: cliente de facturas con descargas autenticadas de PDF/XML.
  • OrderDetailPage.vue: el cliente ve el estado de su factura (CUFE, número DIAN) y descarga PDF/XML.
  • AdminOrders.vue: el admin emite la factura desde el panel (formulario de datos del adquiriente) y consulta/descarga los documentos.

Notas adicionales

  • El frontend está diseñado para consumir la API del backend en local mediante la configuración de CORS y la URL base del cliente API.
  • Para trabajar con el panel de administración, inicia sesión con un usuario administrador o usa las credenciales de seed.
  • Si necesitas cambiar la URL del backend en el frontend, revisa los archivos dentro de frontend/src/api/.