CELLMARCK

Sistema web full-stack para la gestión integral de un taller presencial de reparación de celulares y computadoras.

CELLMARCK administra clientes, equipos, órdenes de trabajo, diagnósticos, cotizaciones, inventario, proveedores, ventas, fidelización y reportes. Incluye un portal privado para clientes, catálogo público y seguimiento seguro de reparaciones.

Características

• Autenticación JWT y permisos por roles.
• Administración de usuarios del personal.
• Registro de clientes con validaciones ecuatorianas.
• Equipos con IMEI o número de serie opcional.
• Órdenes con numeración y código de seguimiento únicos.
• Flujo controlado de estados e historial auditable.
• Diagnósticos y cotizaciones con aprobación del cliente.
• Inventario, movimientos, proveedores y alertas de stock.
• Punto de venta presencial y comprobantes imprimibles.
• Programa de fidelización por ciclos de compras.
• Dashboard diferenciado para administradores y técnicos.
• Reportes por período, exportación CSV e impresión.
• Catálogo y consulta de reparaciones sin iniciar sesión.
• Portal de cliente para trabajos, compras, cotizaciones y perfil.

Stack tecnológico

Frontend

• React 18
• TypeScript
• Vite
• React Router
• Zustand
• Axios
• React Hook Form y Zod
• Tailwind CSS
• Lucide React

Backend

• Python y FastAPI
• Pydantic v2
• SQLAlchemy 2.0 Async
• Alembic
• PostgreSQL mediante asyncpg
• JWT con python-jose
• Passlib y bcrypt
• Pytest y HTTPX

Infraestructura

• Supabase PostgreSQL
• Render para la API
• Vercel para el frontend

Arquitectura

frontend/  React + TypeScript
     │
     │ REST/JSON + JWT
     ▼
backend/   FastAPI + SQLAlchemy Async
     │
     ▼
Supabase PostgreSQL

El frontend no accede directamente a Supabase. Todas las operaciones pasan por FastAPI para aplicar permisos, validaciones y reglas de negocio.

Estructura del repositorio

CELLMARCK/
├── backend/
│   ├── alembic/             # Migraciones
│   ├── app/
│   │   ├── api/v1/          # Endpoints REST
│   │   ├── core/            # Configuración, seguridad y middleware
│   │   ├── db/              # Sesiones y datos iniciales
│   │   ├── models/          # Modelos SQLAlchemy
│   │   ├── schemas/         # Esquemas Pydantic
│   │   └── services/        # Lógica de negocio
│   ├── tests/               # Pruebas de integración
│   └── requirements.txt
├── frontend/
│   ├── public/              # Recursos estáticos
│   ├── src/
│   │   ├── components/
│   │   ├── layouts/
│   │   ├── pages/
│   │   ├── services/
│   │   ├── store/
│   │   ├── types/
│   │   └── utils/
│   └── package.json
├── DEPLOYMENT.md
├── INFORME_TECNICO.md
└── render.yaml

Requisitos

• Python 3.11 o superior
• Node.js 18 o superior
• npm
• PostgreSQL o un proyecto de Supabase

Instalación local

Instalación automática en Windows

Para preparar el proyecto en otro computador Windows:

1. Copia o clona la carpeta completa.
2. Ejecuta INSTALAR_Y_EJECUTAR.bat con doble clic.
3. Si Python 3.11+ o Node.js 18+ no están disponibles, el instalador intentará instalarlos mediante winget.
4. Si no existe backend/.env, pega la cadena DATABASE_URL de Supabase cuando el instalador la solicite. También puedes presionar Enter para usar SQLite.
5. Espera a que se instalen dependencias, se apliquen migraciones y se valide la compilación.

El instalador abrirá el backend y el frontend en ventanas separadas y después abrirá http://127.0.0.1:5173.

En los usos posteriores basta con ejecutar:

INICIAR_CELLMARCK.bat

Este lanzador no reinstala dependencias. Si se actualizan requirements.txt o package-lock.json, vuelve a ejecutar INSTALAR_Y_EJECUTAR.bat.

1. Clonar el repositorio

git clone https://github.com/marco4u41/CELLMARCK.git
cd CELLMARCK

2. Configurar el backend

cd backend
python -m venv venv

En Windows:

.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

En Linux o macOS:

source venv/bin/activate
pip install -r requirements.txt

Copia backend/.env.example como backend/.env y configura:

ENVIRONMENT=development
DATABASE_URL=postgresql+asyncpg://USUARIO:CONTRASEÑA@HOST:5432/postgres
SECRET_KEY=una-clave-larga-y-aleatoria
BACKEND_CORS_ORIGINS=["http://localhost:5173","http://127.0.0.1:5173"]

No publiques el archivo .env.

Aplica las migraciones y carga los datos demostrativos:

alembic upgrade head
python -m app.db.init_db

Inicia la API:

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Documentación interactiva:

• Swagger UI: http://127.0.0.1:8000/api/v1/docs
• Health check: http://127.0.0.1:8000/api/v1/health

3. Configurar el frontend

En otra terminal:

cd frontend
npm install

Opcionalmente crea frontend/.env.local:

VITE_API_URL=http://127.0.0.1:8000/api/v1

Inicia Vite:

npm run dev

Abre http://127.0.0.1:5173.

Usuarios demostrativos

Los datos iniciales crean cuentas destinadas exclusivamente a desarrollo:

Rol	Correo	Contraseña
Administrador	admin@cellmarck.com	AdminPassword123!
Técnico	tecnico@cellmarck.com	TecnicoPassword123!
Cliente	cliente1@cellmarck.com	ClientePassword123!

Cambie estas credenciales antes de utilizar el sistema fuera de un entorno académico o demostrativo.

Pruebas

Backend:

cd backend
python -m pytest -q

Frontend:

cd frontend
npm run build

Despliegue

El repositorio incluye:

• render.yaml para desplegar FastAPI en Render;
• frontend/vercel.json para conservar las rutas SPA en Vercel;
• DEPLOYMENT.md con las variables y verificaciones requeridas.

En producción:

1. configure DATABASE_URL y SECRET_KEY en Render;
2. ejecute alembic upgrade head;
3. configure VITE_API_URL en Vercel;
4. limite BACKEND_CORS_ORIGINS al dominio real;
5. no incluya .env, bases SQLite ni credenciales reales en Git.

Documentación adicional

• Informe técnico
• Guía de despliegue
• Plan de implementación

Autor

Proyecto académico desarrollado para la gestión digital de CELLMARCK.