Saltar a contenido

El front

Una aplicación en React, Vite, Tailwind y shadcn/ui que habla con la API solo por el cliente que genera tai-api (src/api): la sesión, las rutas, los permisos, los tipos y las consultas son los suyos. init la copia a chatbot/app/front/ y desde ahí es tuya.

Lo que trae

Pantalla Quién Qué hace
Entrar Todos Usuario y contraseña del realm del chatbot. La sesión va en una cookie: ningún token se guarda en el navegador
El chat Todos Las conversaciones del usuario; la respuesta mientras se escribe; parar, regenerar y valorar una respuesta (y cambiar la valoración, que se abre con la anterior); elegir el modelo de cada conversación; exportarla; copiar una respuesta o una tabla con su título para pegarla en Word o Excel, o bajar la tabla en CSV; las sugerencias de bienvenida
Mi cuenta Todos El perfil, cambiar la contraseña y lo gastado este mes
Mi consumo Todos Su consumo del mes y día a día, con la caché en su columna
Gestión de usuarios app-gestion-usuarios Alta, baja y roles de los usuarios del realm
Consumo app-consumo El consumo de todos, los límites de cada uno y los modelos, con exportación
Laboratorio app-lab Debajo de cada respuesta: las herramientas que usó el agente, sus argumentos, sus resultados y los tokens

Funciona en móvil, en tema claro y oscuro, y en el idioma de front.idioma.

La marca, desde config.yaml

Sin tocar código, desde la sección front de config.yaml:

  • el nombre de la aplicación;
  • los logos, claro, oscuro y favicon;
  • los colores del tema;
  • el idioma de la interfaz, las fechas y los importes;
  • las sugerencias de la pantalla de bienvenida;
  • el pie «powered by».

tai-chat config generate (y tai-chat dev al arrancar) los escribe en src/marca/ y public/marca/, que no se editan a mano. Ver config.yaml.

Los componentes usan las variables del tema (bg-primary, text-muted-foreground), nunca un color fijo: así lo que declara config.yaml llega a todas partes. Para un color nuevo, se declara la variable en src/index.css y desde ahí se le puede dar valor en config.yaml.

Cómo está organizado

app/front/src/
├── api/              generado por tai-api: no se edita, salvo custom/
│   ├── core/ auth/   el cliente HTTP, los errores, la sesión y los permisos (PERMISSIONS)
│   ├── react/        TaiProvider, useSession, Can, defineRoutes, renderRoutes, useNavigation
│   ├── chatbot/      los tipos, las llamadas y las consultas de cada tabla
│   └── custom/       lo que no genera tai-api, con la misma forma: /assistant, /rbac y /auth/me.
│                     Su index.ts exporta customResources, que createTaiClient registra
├── routes/routes.tsx las pantallas: ruta, permiso y entrada en el menú
├── marca/            derivado de config.yaml. No se edita
├── lib/tai.ts        el cliente (`api`), uno para toda la aplicación
├── lib/queryClient.ts  la caché de TanStack Query, una para toda la aplicación
├── services/         chatService: el WebSocket de la sesión, lo que se está escribiendo en cada
│                     conversación y la forma de los mensajes
├── hooks/            las consultas y mutaciones de TanStack; useCuenta, el usuario con su perfil;
│                     useRespuesta y useMarcaDeChat, lo que está respondiendo; useTituloEscrito,
│                     el título que pone el modelo, letra a letra
├── contexts/         la conversación abierta (la sesión es la de tai-api: TaiProvider y useSession)
├── components/       la interfaz; components/ui, las piezas de shadcn
└── pages/            las pantallas

Todo pasa por un solo api (import { api } from "@/lib/tai"): api.chatbot.*, la gestión de usuarios (api.rbac(REALM)) y la sesión con el perfil (api.session.me()) los genera tai-api, y api.assistant.* es lo propio, que vive en src/api/custom/ y createTaiClient registra igual que la API monta routers/custom/. Lo que se lee es una consulta de TanStack y lo que se escribe, una mutación; ESLint no deja escribir una queryKey a mano, ni crear otro cliente.

La invalidación es por tablas: cada consulta sabe qué tablas lee, y una mutación invalida las que leen la tabla en la que escribe o una vecina suya. Las mutaciones son factorías, y lo que se le pasa se suma a la invalidación: useMutation(m.chat.create({ onSuccess: cerrar })).

Leer datos nuevos en el front

Cuando la API expone un schema nuevo —como mantenimiento en Herramientas que leen datos—, tai-chat api generate genera también sus consultas en el cliente. Una pantalla que lista las averías del usuario no necesita ni una llamada escrita a mano:

import { useQuery } from "@tanstack/react-query";
import { mantenimientoQueries } from "@/api/mantenimiento/query";
import { api } from "@/lib/tai";

const consultas = mantenimientoQueries(api);

export function MisAverias() {
  const { data, isLoading } = useQuery(
    consultas.averia.findMany({ estado: "abierta", order_by: ["abierta_en"], order: "DESC" }),
  );
  if (isLoading) return <p>Cargando…</p>;
  return (
    <ul>
      {data?.data.map((a) => <li key={a.id}>{a.descripcion}</li>)}
    </ul>
  );
}

La API aplica los permisos y las reglas de fila, así que cada usuario ve sus averías: las mismas que le devuelven las herramientas del asistente.

Un endpoint propio

Un endpoint que añades en routers/custom/ no lo genera tai-api: se llama desde src/api/custom/, con la misma forma que lo generado. Por ejemplo, un GET /assistant/resumen:

// src/api/custom/assistant/resources.ts, dentro de assistantResources(http)
resumen: (opts: CallOptions = {}) =>
  http.request<Resumen>({ method: "GET", path: "/assistant/resumen", ...opts }),
// src/api/custom/assistant/query.ts, dentro de assistantQueries(api)
resumen: () => chatbotQuery({
  key: ["assistant", "resumen"],
  tables: ["chat", "mensaje"],        // lo que lee: una escritura en ellas la vuelve a pedir
  queryFn: ({ signal }) => r.resumen({ signal }),
}),

Resumen se declara en models.ts. En la pantalla, useQuery(assistantQueries(api).resumen()). No hace falta inventar una key: chatbotQuery la pone, y a la consulta le llega la invalidación de las tablas que declara. Una escritura propia es chatbotMutation(queryClient, { tables, mutationFn }). Va por el cliente HTTP de tai-api: la misma sesión, el mismo refresco del token y los mismos errores. Un dominio nuevo (otra carpeta en custom/) se añade a la lista de custom/index.ts; con eso está en api con sus tipos. El src/api/index.ts generado tiene su propia zona para lo propio, con estos pasos, pero no es donde se añade: lo reescribe tai-chat api generate.

// src/api/custom/index.ts: la lista de lo propio, un dominio por línea
export const customResources = defineCustomResources({
  assistant: assistantResources,
  informes: informesResources,           // el nuevo: api.informes.*
  // facturas: facturasResources(REALM), // uno que necesita algo más lo recibe y devuelve el dominio
});

Nada de custom/ importa .. (el index.ts del cliente importa a custom/: sería un ciclo), y un nombre que choque con http, session, rbac o un schema no compila. Si custom/ no existía al generar, tai-chat api generate lo registra.

Una pantalla nueva

Las pantallas se declaran una vez, en src/routes/routes.tsx: de ahí salen la ruta, si pide sesión, su permiso y su entrada en el menú de la barra lateral. Para que la del ejemplo salga en el menú solo a quien tenga un permiso de aplicación nuevo:

# api/rbac/chatbot.py
averias = app_permission("app-averias", description="Ve las averías")
// src/routes/routes.tsx
{
  path: "/averias",
  label: "Mis averías",
  icon: Wrench,
  element: <MisAveriasPage />,
  permission: PERMISSIONS.APP.AVERIAS,
},

PERMISSIONS lo genera tai-api desde rbac/chatbot.py al hacer tai-chat api generate: un permiso mal escrito no compila. Sin el permiso, la ruta vuelve al chat y el menú no la enseña. Un botón se esconde con <Can permission={PERMISSIONS.APP.AVERIAS}>. Esconder no es autorizar: quien decide es la API.

En desarrollo

tai-chat dev app      # solo el front, en http://localhost:4713

El front llama a /api, y el proxy de Vite lo reenvía a la API en el mismo origen, WebSocket incluido: así funciona la cookie de sesión. El puerto es front.puerto de config.yaml.