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.
$ git clone https://github.com/YANCARLOSOFICIAL/Tienda-de-celulares-ecommerce-.git
$ cd Tienda-de-celulares-ecommerce-
// puntos clave
// key points
- 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.
// README.md del repositorio
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-stoppedvuelve a levantar los contenedores cuando reinicia Docker Desktop o la máquina — ya no hay que hacerupcada vez que se reabre el proyecto.- El código de
backend/appestá 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 PostgreSQLSECRET_KEY: clave secreta para JWTACCESS_TOKEN_EXPIRE_MINUTES: duración del tokenCORS_ORIGINS: orígenes permitidos por CORSSEED_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 defectov2). La V2 usa códigos DIAN (identification_document_code,unit_measure_code...), precios sin IVA ypayment_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).
- Autenticación OAuth2: el servicio solicita el token a
POST /oauth/token(grantpassword) y lo renueva automáticamente con el grantrefresh_tokencuando expira (~1 hora). - 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.
- Persistencia: el resultado (CUFE, número, estado DIAN, respuesta cruda) se guarda en la tabla
invoices. - 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_URLahttps://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/.