Organización de proyecto, componentes y librerías UI

3.1Puente uno: es un parámetro de función

Esto lo escribiste en la primera ayudantía:

function saludar(nombre) {
  return 'Hola ' + nombre
}

saludar('Vicente')
saludar('Nelson')

Nadie escribiría una función saludarAVicente() y otra saludarANelson(). El nombre entra como parámetro, y una sola función sirve para los dos.

Un componente funciona exactamente igual:

function Boton({ texto }) {
  return <button>{texto}</button>
}

<Boton texto="Guardar" />
<Boton texto="Cancelar" />

• 1texto es el parámetro. Llega desde afuera y el componente no lo elige.
• 2Adentro se usa igual que cualquier variable. El componente no sabe ni le importa qué dice.
• 3Y acá se le pasa el valor. Mismo componente, dos botones distintos.

3.2Puente dos: es un atributo de HTML

Llevas años escribiendo esto sin pensarlo:

<img src="foto.png" alt="Una foto">

src y alt son datos que le pasas a la etiqueta desde afuera. Las props son el mismo gesto, con una diferencia: el nombre lo inventas tú. texto, variante, mesa, lo que el componente necesite.

3.3Pruébalo

Mueve las props de la izquierda y mira el botón y su JSX. Es el mismo componente en los tres casos.

3.4La parte que de verdad cuesta

Las props son de solo lectura. Entran, el componente las usa, y no las puede modificar. Si necesita que algo cambie, no lo cambia él: avisa hacia arriba con un evento y decide quien lo usó.

// el botón solo avisa que lo apretaron
function Boton({ children, onClick }) {
  return <button onClick={onClick}>{children}</button>
}

// la pantalla decide qué hacer con ese aviso
<Boton onClick={guardarReserva}>Guardar</Boton>

De ahí sale la frase props abajo, eventos arriba. El que llama manda; el llamado obedece. Igual que con los argumentos de una función.

3.5El criterio que te tienes que llevar

Con esa frase resuelves casi todas las dudas de diseño de un componente. El texto cambia entre un botón y otro, así que es prop. El padding y el border-radius son iguales siempre, así que se quedan adentro.

3.6Chequeo rápido

Si puedes responder esto sin mirar, lo tienes.

1. Tengo un botón que dice «Guardar» y necesito uno que diga «Cancelar». ¿Qué tiene que entrar por props?El texto.
2. ¿Y si además uno es rojo y el otro gris?El color también. Dos props: el texto y la variante.
3. ¿Y el border-radius, que es igual en los dos?Se queda adentro del componente. No cambia entre un uso y otro, así que no es prop.

4.0Los tres tipos de componente

Es la duda que más se repite. Para probarlo, pregúntate:

Los casos que confunden

• Boton → ui/. Recibe texto, variante y un onClick. No sabe si guarda una reserva o borra un usuario.
• Sidebar → components/. Tiene los módulos de este sistema y sabe qué opciones esconder según el rol.
• DataTable → components/. Aunque es genérica, está pensada para las tablas de este proyecto y usa su estilo. Si la hicieran del todo agnóstica, podría subir a ui/.
• EstadoReserva, la insignia que pinta «confirmada» en verde → components/, porque conoce los estados del negocio. La insignia genérica (Badge, que solo recibe color y texto) sí va en ui/.
• Modal → ui/. ModalConfirmarReserva → components/, porque sabe qué pregunta hacer.
• RutaProtegida → components/. Lee el contexto de sesión de esta aplicación.

La separación sirve para algo concreto: components/ui/ es lo que se pueden llevar completo al próximo proyecto, y es donde va a vivir el envoltorio de MUI o ShadCN. Tenerlo aparte deja claro qué es reutilizable y qué está amarrado a este sistema.

4.1El mesero que se metió a la cocina

El caso completo: crear una reserva validando que la mesa no esté ocupada.

export const crear = async (req, res) => {
  const { mesaId, inicio, fin } = req.body

  if (!mesaId || !inicio || !fin)
    return res.status(400).json({ error: 'Faltan campos' })

  if (new Date(inicio) >= new Date(fin))
    return res.status(400).json({ error: 'Rango invalido' })

  const choque = await prisma.reserva.findFirst({
    where: { mesaId, inicio: { lt: fin }, fin: { gt: inicio } }
  })
  if (choque)
    return res.status(409).json({ error: 'Mesa ocupada' })

  const r = await prisma.reserva.create({ data: { mesaId, inicio, fin } })
  res.status(201).json(r)
}

• 1Revisa la forma del formulario. Eso es trabajo del anfitrión de la puerta.
• 2Decide una regla del negocio. Esto es lo grave: la regla es tuya, no de HTTP, y encerrada acá no se puede llamar desde ningún otro lado.
• 3Habla directo con la bodega. Un controlador no debería tener un prisma. adentro.
• 4Y recién acá hace lo suyo: armar la respuesta HTTP.

export const crear = async (req, res, next) => {
  try {
    const r = await reservaService.crear(req.body)
    res.status(201).json(r)
  } catch (e) { next(e) }
}

export const crear = async ({ mesaId, inicio, fin }) => {
  if (new Date(inicio) >= new Date(fin))
    throw Object.assign(new Error('Rango invalido'), { status: 400 })

  const choque = await prisma.reserva.findFirst({
    where: { mesaId, inicio: { lt: fin }, fin: { gt: inicio } }
  })
  if (choque)
    throw Object.assign(new Error('Mesa ocupada'), { status: 409 })

  return prisma.reserva.create({ data: { mesaId, inicio, fin } })
}

// validarReserva.js — revisa la FORMA del pedido
export default function validarReserva(req, res, next) {
  const { mesaId, responsable, inicio, fin } = req.body
  if (!mesaId || !responsable || !inicio || !fin)
    return res.status(400).json({ error: 'Faltan campos obligatorios' })
  next()
}

// manejarErrores.js — el único que arma respuestas de error
export default function manejarErrores(err, req, res, next) {
  res.status(err.status || 500).json({ error: err.message })
}

4.2Cómo se encadena todo en las rutas

import { Router } from 'express'
import * as reservaController from '../controllers/reserva.controller.js'
import validarReserva from '../middlewares/validarReserva.js'

const router = Router()
router.get('/', reservaController.listar)
router.post('/', validarReserva, reservaController.crear)
//              ↑ primero el anfitrión, después el mesero
export default router

// app.js — arma el restaurante, pero no abre la puerta
app.use(express.json())
app.use('/api', rutas)
app.use(manejarErrores)   // va al final, SIEMPRE
export default app

// index.js — abre la puerta, y eso es todo
app.listen(3000)

Están separados para que puedas importar la app en un test sin ocupar el puerto 3000 de la máquina. Es el mismo motivo por el que un restaurante se puede montar antes de abrir.

4.3Una sola conexión a la bodega

Este es el error más común del semestre. Prisma abre un grupo de conexiones por cada cliente que creas.

const prisma = new PrismaClient()   // ← y otro, y otro, y otro…

import { PrismaClient } from '@prisma/client'
export const prisma = new PrismaClient()

// y en todos los demás archivos:
import { prisma } from '../config/prisma.js'

4.4La puerta única al backend

useEffect(() => {
  fetch('http://localhost:3000/api/reservas', {
    headers: { Authorization: 'Bearer ' + token }
  }).then(r => r.json()).then(setReservas)
}, [])

import axios from 'axios'

export const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL
})

// le pega el token a TODAS las peticiones, una sola vez
api.interceptors.request.use(cfg => {
  const token = localStorage.getItem('token')
  if (token) cfg.headers.Authorization = `Bearer ${token}`
  return cfg
})

// y si el backend dice 401, cierra sesión en un solo lugar
api.interceptors.response.use(r => r, err => {
  if (err.response?.status === 401) {
    localStorage.removeItem('token')
    window.location.href = '/login'
  }
  return Promise.reject(err)
})

import { api } from './api.js'

export const listar = () => api.get('/reservas').then(r => r.data)
export const crear  = datos => api.post('/reservas', datos).then(r => r.data)

4.5Un componente reutilizable, completo

function BotonGuardarReserva() {
  return <button className="btn-azul" onClick={() => guardarReserva()}>
    Guardar reserva
  </button>
}
// sabe qué dice, de qué color es y qué hace. Sirve en un solo lugar.

const estilos = {
  primario:   'bg-blue-600 text-white',
  secundario: 'bg-gray-200 text-gray-900',
  peligro:    'bg-red-600 text-white'
}

export default function Boton({
  children,
  variante = 'primario',
  cargando = false,
  ...props
}) {
  return (
    <button
      className={`px-4 py-2 rounded font-medium ${estilos[variante]}`}
      disabled={cargando || props.disabled}
      {...props}
    >
      {cargando ? 'Cargando…' : children}
    </button>
  )
}

• 1children es qué dice el botón. Entra desde afuera.
• 2variante es de qué color, con un valor por defecto para no repetirlo en cada uso.
• 3cargando lo deshabilita y le cambia el texto mientras espera.
• 4...props deja pasar todo lo demás: onClick, type, aria-label. Esto es lo que más se olvida, y sin ello hay que volver a editar el componente el día que necesites un type="submit".

<Boton onClick={guardar} cargando={guardando}>Guardar</Boton>
<Boton variante="peligro" onClick={borrar}>Eliminar</Boton>
<Boton variante="secundario" type="button" onClick={cerrar}>Cancelar</Boton>

4.6children: el hueco que deja el componente

export default function Card({ titulo, acciones, children }) {
  return (
    <section className="card">
      <header>
        <h3>{titulo}</h3>
        {acciones}          // ← otro hueco, pero arriba
      </header>
      {children}            // ← el hueco principal
    </section>
  )
}

<Card titulo="Reservas de hoy" acciones={<Boton>Nueva</Boton>}>
  <DataTable columnas={cols} datos={reservas} vacio="Sin reservas" />
</Card>

<Card titulo="Nueva reserva">
  <FormularioReserva onGuardar={crear} />
</Card>

children no tiene que ir al final. Un Layout con menú arriba y contenido abajo pone el hueco entre medio. Y puedes tener varios huecos, como el acciones del ejemplo.

4.7La tabla genérica

export default function DataTable({ columnas, datos, vacio }) {
  if (!datos.length) return <p className="vacio">{vacio}</p>

  return (
    <table>
      <thead>
        <tr>{columnas.map(c => <th key={c.campo}>{c.titulo}</th>)}</tr>
      </thead>
      <tbody>
        {datos.map(fila => (
          <tr key={fila.id}>
            {columnas.map(c => (
              <td key={c.campo}>{c.render ? c.render(fila) : fila[c.campo]}</td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  )
}

const columnas = [
  { campo: 'mesa',        titulo: 'Mesa',   render: r => r.mesa.numero },
  { campo: 'responsable', titulo: 'Responsable' },
  { campo: 'inicio',      titulo: 'Desde',  render: r => formatearHora(r.inicio) }
]

<DataTable columnas={columnas} datos={reservas} vacio="Sin reservas para hoy" />

4.8El hook que evita copiar el mismo useEffect

import { useEffect, useState, useCallback } from 'react'

export function useFetch(fn) {
  const [datos, setDatos]       = useState([])
  const [cargando, setCargando] = useState(true)
  const [error, setError]       = useState('')

  const recargar = useCallback(() => {
    setCargando(true)
    fn().then(setDatos)
        .catch(e => setError(e.message))
        .finally(() => setCargando(false))
  }, [fn])

  useEffect(() => { recargar() }, [recargar])

  return { datos, cargando, error, recargar }
}

Y en la pantalla queda una línea: const { datos: reservas, cargando, recargar } = useFetch(useCallback(reservaService.listar, []))

4.9Envolver la librería UI

import { Button } from '@mui/material'

export default function Boton({ children, ...props }) {
  return (
    <Button variant="contained" disableElevation {...props}>
      {children}
    </Button>
  )
}

import { Button } from '@/components/ui/button'

export default function Boton({ children, ...props }) {
  return <Button {...props}>{children}</Button>
}
// las treinta pantallas no se enteran de nada

5.1Qué te da de verdad una librería UI

No es que se vea bonito. Es todo lo que un componente hecho a mano no tiene y nadie se acuerda de programar. El ejemplo más claro es un modal, que parece un div encima de otro.

5.2Dos familias, no dos productos

5.3Dónde queda el código de cada familia

La diferencia práctica no es cómo se ven. Es dónde vive el archivo y quién lo puede editar.

npm install @mui/material

npx shadcn@latest add button

5.4Criterios para elegir

Seis preguntas. Respóndanlas en grupo, no cada uno por su cuenta.

5.5Sea cual sea, va detrás de un wrapper

La librería no debería aparecer importada fuera de components/ui/. Sin wrapper queda importada en treinta archivos, y cambiarla es abrir los treinta. Con wrapper, un solo archivo del proyecto la conoce.

src/
├── components/
├── pages/
├── hooks/
├── services/
└── utils/

src/
├── features/
│   ├── reservas/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── reservaService.js
│   │   └── ReservasPage.jsx
│   └── mesas/
│       ├── components/
│       ├── mesaService.js
│       └── MesasPage.jsx
└── shared/
    ├── components/ui/
    ├── services/api.js
    └── utils/

6.1En el restaurante

Por tipo es ordenar la cocina por tipo de utensilio: todos los cuchillos en un cajón, todas las ollas en otro.

Por módulo es ordenarla por estación: la estación de postres tiene sus propios cuchillos, sus propias ollas y su propio horno.

6.2Cuándo conviene cada una

6.3El error típico de «por módulo»

Poner todo dentro de los módulos y quedarse sin lugar para lo compartido.

7.1Los cinco pasos

1. Rama aparte, siempre Nunca directo a dev y muchísimo menos a main. Si algo sale mal, se borra la rama y no pasó nada.

   git switch -c refactor/estructura

2. Usa git mv, no arrastres carpetas Si arrastras en el explorador, Git lo ve como un archivo borrado y otro creado: pierdes el historial y la autoría.

   git mv src/todo.js src/services/mesaService.js

3. Un movimiento, un commit Es el mismo criterio de la Ayudantía 1. Si el commit mueve ocho cosas, no puedes revertir solo la que falló.

   git commit -m "chore(struct): mueve la logica de reservas a services/"

4. Mover no es cambiar Si aprovechas de corregir un bug en el mismo commit y algo se rompe, no vas a saber si fue el movimiento o el arreglo. Primero mueves; en otro commit, arreglas.
5. Levanta el proyecto en cada paso Un import roto no siempre avisa al compilar. Avisa en el navegador, cuando entras a la pantalla.

   npm run dev   # en los dos lados, y haz clic de verdad

7.2En qué orden mover las cosas

De abajo hacia arriba, para que cada paso deje el proyecto funcionando:

1. Primero el backend, que es más fácilSaca las consultas del controlador a un service. Un recurso a la vez.
2. Después services/api.js en el frontendCrea el archivo, y ve cambiando pantalla por pantalla para que use el servicio en vez de llamar directo.
3. Después mueve las pantallas a pages/Es solo mover archivos y arreglar imports.
4. Al final, extrae los componentes repetidosEsto es lo único que requiere pensar, y por eso va último, cuando el resto ya está ordenado.

7.3Errores que van a cometer

• Mover un archivo y olvidar un import. Vite avisa en el navegador, no en la terminal. Hagan clic en todas las pantallas después de cada paso.
• Renombrar de tabla.jsx a DataTable.jsx en Windows. Git a veces no detecta el cambio de mayúsculas. Si pasa, usen git mv tabla.jsx temporal.jsx y después a DataTable.jsx.
• Mover el .env sin actualizar el .env.example. Al compañero que clone le va a faltar una variable y no va a saber cuál.
• Hacer el refactor en la misma rama donde alguien está trabajando. El merge va a ser una pesadilla. Avisen en el grupo antes de empezar.

8.1Cómo levantarlo

Necesitas Node 18 o superior. Nada más: ni base de datos ni configuración.

# terminal 1 — el backend
cd server
npm install
npm run dev          # queda en http://localhost:3000

# terminal 2 — el frontend
cd client
npm install
npm run dev          # queda en http://localhost:5173

8.2Las dos ramas

8.3La comparación que vale la pena

# qué archivos cambiaron, y cuánto
git diff desordenado ordenado --stat

# el cambio completo de un archivo
git diff desordenado ordenado -- server/index.js

# saltar de una versión a la otra
git switch desordenado
git switch ordenado

8.4Ejercicios, si quieren practicar

1. Agrega un campo nuevoQue la reserva tenga un «motivo». Hazlo primero en la rama desordenada y después en la ordenada, y cuenta cuántos archivos tocaste en cada una.
2. Agrega una reglaQue no se pueda reservar una mesa por más de cuatro horas seguidas. ¿Dónde va esa regla? Pista: es de la cocina.
3. Cambia el color de todos los botonesEn la rama ordenada es un archivo. En la desordenada, anda a buscarlos.
4. Agrega una tercera pantallaUn listado de usuarios. En la rama ordenada puedes reusar DataTable; en la otra vas a terminar escribiendo tabla3.jsx.