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:
// 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¶
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.