# EnglishWorldCenter Chatbot — instrucciones para agentes

Plataforma de práctica de idiomas con bots conversacionales de voz para
English World Center (EWC). Integra ElevenLabs (voz) y OpenAI (traducciones y
feedback, opcional). Tres roles: ADMIN, TEACHER, STUDENT. Producción:
https://chat.englishworldcenter.com

Este archivo es la **única fuente de instrucciones** para agentes: lo lee Codex
y Claude Code lo importa desde `CLAUDE.md`. Si algo cambia, se cambia aquí, no
en otro archivo.

## Dónde está cada cosa

- **Solo lo que está dentro de este repo va a GitHub.** Lo que tenga que estar
  en GitHub tiene que estar aquí dentro.
- Al lado del repo (`../`) está la carpeta local de Carla, que **no se sube**:
  - `../encargos/`: propuestas, precios y material de cada encargo de EWC.
  - `../documentacion/`: guías de usuario entregadas a EWC.
  - `../DOCUMENTACION-TRASPASO.md`: traspaso entregado a EWC, con los accesos
    al servidor. **No se toca**, no se copia nada de él y sus credenciales no
    se citan nunca.
- Documentación técnica: índice en [docs/README.md](docs/README.md). Al empezar
  una tarea, lee [docs/status.md](docs/status.md): qué hay en producción y qué
  falta.
- Lo que haya en `../encargos/` es una foto de antes de implementar. La verdad
  actual es el código y `docs/`.

## Glosario

- **Auxiliar** (en inglés, *assistant*): así llama la interfaz a los bots desde
  el 24-sep-2026 (`7a7107a`). En el código sigue siendo `Bot`; cada bot apunta
  a un agente de ElevenLabs (`agentId`).
- **Asignación**: un alumno tiene acceso a un auxiliar (`StudentBotAccess`).
- **Cuota** del alumno (base + extra) y **tiempo del bot**: dos límites
  distintos, ver «Cuotas y tiempo de uso».
- **R1–R5, F1–F5, G1–G2**: puntos del plan de mejoras de julio-agosto de 2026
  (Fases 1, 2 y 3). Salen en commits y en `docs/`; qué es cada uno, en
  [CHANGELOG.md](CHANGELOG.md).

## Stack

- **Frontend** (`frontend/`): Vue 3 (Composition API + `<script setup>`),
  Vite, Pinia, Vue Router 4, Bootstrap 5, Lucide icons, Axios, TypeScript.
- **Backend** (`backend/`): Node.js ≥ 22, Express 4, TypeScript, JWT en
  cookies httpOnly, Winston, Zod, WebSocket (`ws`) en `/ws`.
- **BD**: PostgreSQL 15 + Prisma. Esquema único en `prisma/schema.prisma`
  (raíz del repo, NO dentro de `backend/`); los scripts de backend usan
  `--schema=../prisma/schema.prisma`.
- **Infra**: Docker Compose con perfiles `dev` y `prod`; contenedor Temporal.
  En producción Apache es el reverse proxy **del host**, pero el estático lo
  sirve un nginx **dentro** del contenedor `frontend-prod`; de los cuatro
  `frontend/nginx.conf*` el único que se usa es `nginx.conf.PROD.container`
  (`Dockerfile.prod`).
- Package manager: **npm** en los tres niveles (raíz, backend, frontend).
  El `package.json` de la raíz no tiene scripts pero NO es residual: sus
  dependencias las usan `create-admin-user.js` y los scripts de `test/*.js`.
  El código de la app vive en `backend/` y `frontend/`.

## Comandos

```bash
# Entorno completo en local (frontend 5173, API 3000, health /health)
docker compose --profile dev up -d --build
docker compose --profile dev logs -f backend
docker compose --profile dev down            # -v borra la BD, no usarlo a la ligera

# Backend sin Docker (backend/)
npm run dev              # tsx watch
npm run build && npm run start
npm run lint / lint:fix / format
npm run prisma:generate / prisma:migrate / prisma:deploy / prisma:studio / prisma:seed

# Frontend sin Docker (frontend/)
npm run dev
npm run build            # incluye type-check (vue-tsc); la verificación fiable
npm run lint             # ojo: es `eslint . --fix`, MODIFICA los archivos
npm run format
```

Sin perfil (`docker compose up`) no arranca ningún frontend: `frontend-dev`
y `frontend-prod` están detrás de los perfiles `dev`/`prod`.

## Arquitectura

- `backend/src/index.ts` — entrada Express; exporta `prisma` (PrismaClient).
- `backend/src/routes/` → `controllers/` → `services/` (ElevenLabs, OpenAI,
  conversaciones); `middlewares/` (auth JWT, roles, errores); `utils/`.
- `backend/src/prisma/seed.ts` — seed (usuarios demo `@example.com`).
- `backend/docker-entrypoint.sh` — en Docker: migra (`PRISMA_MIGRATE`) o
  `db push`, seed opcional (`RUN_SEED`), build y arranque.
- `frontend/src/views/` — `admin/`, `teacher/`, `public/` y `shared/`. **No
  hay `views/student/`**: lo que ve el alumno vive en `shared/` (`BotsView`,
  `ChatView`, `HomeView`…), condicionado por rol dentro del propio componente.
  Lo único bajo `student/` son componentes
  (`components/student/ChatTimer.vue`).
- `stores/` (Pinia, auth), `services/` (capa API Axios), `router/` (guards
  por rol con meta `requiresAuth`/`roles`), `components/`, `composables/`,
  `i18n/`.
- Rutas API bajo `/api/*`: auth, users, bots, bot-assignments, conversations,
  feedback, statistics, notifications, usage, openai, system-config,
  elevenlabs, elevenlabs-voice.
- Flujo de una llamada (WebSocket, ElevenLabs, feedback, traducciones):
  [docs/features/conversations.md](docs/features/conversations.md).

## Roles y permisos

Hay tres roles (`UserRole`), pero el permiso real es más fino: `User` tiene
flags `canCreateBots` / `canEditBots`, así que un TEACHER no puede crear ni
editar bots salvo que se le activen.

- Backend: helpers en `middlewares/auth.ts` — `requireAdmin`,
  `requireTeacherOrAdmin`, `requireAuthenticated`, `authorize(...roles)` y
  `requireBotPermission(flag)`.
- Frontend: guards por `meta.roles` en `router/index.ts`.
- Varias vistas de `shared/` las usan los tres roles y ramifican con
  `userRole` (`BotsView.vue` es el caso extremo). Al tocarlas, comprobar los
  tres, no solo el rol con el que estés probando.
- Quién ve qué: `StudentBotAccess` (+ `botAccessService`) da acceso
  alumno→bot; `StudentTeacherAssignment` relaciona profesor↔alumno.

## Cuotas y tiempo de uso

Son dos límites distintos, no confundirlos. Detalle en
[docs/features/quotas.md](docs/features/quotas.md).

- **Cuota del alumno**: modelos `QuotaGrant` (base y extra) + `UsageLedger`,
  `quotaService` y los middlewares `enforceUserMonthlyQuota` /
  `attachQuotaInfo`. **Ya no es mensual** desde `2b9e5ce` (24-oct-2026): el
  nombre del middleware es histórico. Solo se aplica a STUDENT y con la
  gestión de cuotas activada; ADMIN y TEACHER están exentos. Solo la gestiona
  el admin (`components/admin/UserQuotaManager.vue`). Durante la llamada la
  corta el WebSocket.
- **Tiempo del bot**: campos `isTimerEnabled` / `maxUsageSeconds` del modelo
  `Bot`, mostrado con `components/student/ChatTimer.vue`.

## Convenciones

- TypeScript estricto en ambos lados; ESLint + Prettier (`npm run lint`,
  `npm run format` en cada paquete).
- Prisma: modelos PascalCase, campos camelCase, enums para valores fijos
  (UserRole, Level). Cambios de esquema siempre vía migraciones en desarrollo
  (`npm run prisma:migrate`), nunca editando la BD a mano.
- Controllers con `try/catch` + `next(error)`; logging con Winston, no
  `console.log` en backend.
- La API key de ElevenLabs se configura desde el panel admin del frontend
  (tabla de configuración en BD), no solo por `.env`.
- Mensajes de commit en inglés con los prefijos que ya usa el historial:
  `feat` / `fix` / `security` / `i18n` / `refactor` / `style` / `docs` /
  `chore`. Rama de trabajo: `main`.

### i18n (obligatorio)

vue-i18n en modo `legacy: false`, locales en `frontend/src/i18n/locales/`
(`es.ts` y `en.ts`). Idioma por defecto ES, persistido en localStorage
(`app_locale`). Todo texto visible pasa por `t('...')`, y toda clave nueva se
añade a **los dos** ficheros de locale.

### Desplegables: `AppSelect`, nunca `<select>` nativo

`components/AppSelect.vue` sustituye al `<select>` nativo en toda la app (el
desplegable abierto del nativo lo pinta el SO y no acepta el color de marca).
Tres trampas que ya han costado tiempo:

- Usa `<script setup>`, así que **hay que importarlo**. Si se olvida no hay
  error de build ni de lint: solo un warning en consola y el desplegable
  desaparece de la página (pasó en `BotsView`, arreglado en `0ab0e14`).
- Tiene `inheritAttrs: false`: `class` e `id` van a su botón interno, no a la
  raíz. No se le puede dar ancho desde fuera con una clase.
- Su raíz es un `<div>` sin ancho propio: dentro de un `d-flex` colapsa al
  ancho de su texto. Ahí hay que envolverlo en un `<div class="flex-grow-1">`.

`components/common/FormSelect.vue` es el componente antiguo, vivo solo en
`RegisterView.vue`. No usarlo en código nuevo.

Colores, logos y reglas de estilos: [docs/branding.md](docs/branding.md).

## Testing

No hay framework de tests configurado. `test/` contiene scripts Node ad-hoc
(`node test/simple-test.js`, etc.) que se ejecutan desde la raíz del repo
contra la API levantada y usan las dependencias del `package.json` raíz
(ver `test/README-BOT-CRUD-TESTS.md`). No asumir jest/vitest.

El login y el refresh del token rechazan los User-Agent de bots
(`blockBotsOnAuth`, en `middlewares/botDetection.ts`): para probar con
Playwright u otro navegador automatizado, pon un User-Agent de navegador
normal. No hay registro público: los usuarios de prueba los crea el admin
(`POST /api/users`).

## Deploy y producción

- Procedimiento completo y problemas conocidos:
  [docs/operations.md](docs/operations.md). Los accesos al servidor están en
  `../DOCUMENTACION-TRASPASO.md` (fuera del repo, no se toca).
- Deploy inicial: `./deploy-to-server.sh <dominio> <email>` (Apache + Certbot,
  systemd, cron de backup). Actualizaciones: `./upgrade-production.sh`
  (interactivo, hace backup y `git pull`; pedir snapshot del VPS antes).
- Producción: `docker compose --profile prod up -d --build`. Frontend estático
  en host 8080, backend 3000, contenedores `ai-learning-platform-ewc-*`.
- La BD real se llama **`ai_learning_platform`** (lo que dicen
  `docker-compose.yml` y los scripts); ignorar `englishworldcenter` si aparece
  en `env.production`/`.env.prod`.
- `VITE_API_URL` se embebe en **build time**: tras cambiarla hay que
  reconstruir `frontend-prod` (`build --no-cache`).
- Nunca `docker compose down -v` en producción (borra la BD).
- `scripts/migrate-database.sh` dice «OK» aunque falle una migración (ver
  `docs/status.md`): tras un despliegue con migración, comprobar el estado a
  mano como explica `docs/operations.md`.
- Los `.env` contienen secretos y no se commitean. No mostrarlos ni copiarlos.

## Notas para agentes

- Entorno de trabajo: macOS. Todos los scripts de operación son `.sh`
  (los `.ps1` de Windows se eliminaron del repo en julio 2026).
- **Verificación**: `npm run build` en `frontend/` (incluye `vue-tsc`) es la
  comprobación fiable, pero no detecta componentes usados sin importar. En
  `backend/`, `npm run lint` no funciona (falta `eslint.config.js` para
  ESLint 9; ver `docs/status.md`): usa `npm run build` (`tsc`).
- El lint del frontend arroja ~230 errores preexistentes (`no-explicit-any` y
  `require()` en `tests/*.cjs`). No son regresiones tuyas: compara el total
  antes y después del cambio en vez de intentar dejarlo a cero.
- `version.json` lo genera un plugin de `vite.config.ts` en cada build; lo
  sondea `useVersionCheck` cada 5 min para enseñar `UpdateAvailableBanner` a
  quien tenga abierto un build viejo. No se toca a mano.
- WebSocket: el servicio real es `websocketService.ts` (lo arranca
  `index.ts`). `simpleWebSocketService.ts` está exportado pero no lo importa
  nadie: código muerto, no partir de él.
- Auth por cookie httpOnly `accessToken`; la conexión `/ws` también la valida
  (no confía en lo que diga el cliente).

## Arnés y CI

Lo que comprueba las reglas sin depender de que alguien se acuerde
([specs/001-arnes/](specs/001-arnes/spec.md)):

- **CI** (`.github/workflows/ci.yml`): en cada push y cada pull request a
  `main`, compila el backend y el frontend y ejecuta `npm run check:docs`. Si
  falla, no se despliega hasta arreglarlo.
- **`npm run check:docs`**, desde la raíz del repo: comprueba los enlaces de
  toda la documentación.
- **Hooks de Claude Code**, en `../.claude/` (fuera del repo). Solo funcionan si
  Claude Code se abre en `EWC-BOT/`:
  - piden confirmación antes de leer o tocar un `.env`;
  - bloquean cualquier modificación de `../DOCUMENTACION-TRASPASO.md`;
  - comprueban los enlaces al editar un `.md`;
  - al terminar, recuerdan actualizar la documentación si ha cambiado código.

## Documentación: cómo se trabaja

**Antes de empezar**

- Lee `docs/status.md` y el documento de `docs/` de la parte que vas a tocar
  (índice en `docs/README.md`).
- Si algo del código parece raro, búscalo en `docs/decisions.md` antes de
  «arreglarlo»: puede ser intencionado.
- Trabajo nuevo no trivial (una funcionalidad, o un cambio de BD, permisos o
  cuotas): primero una spec en `specs/NNN-tema/` (ver `specs/README.md`), y la
  aprobación de Carla. Los bugs pequeños no necesitan spec.

**Al terminar** (en el mismo commit o en un `docs:` justo después)

- `CHANGELOG.md`, si cambia algo que se nota (para el usuario, en la API o en
  el despliegue).
- `docs/status.md`: quitar lo hecho y añadir lo que quede pendiente.
- `docs/features/*.md`, si cambia cómo funciona algo, y `docs/decisions.md`, si
  se ha decidido algo entre varias opciones.
- Si cambia lo que ve el usuario, avisar de que hay que revisar las guías de
  usuario (`../documentacion/`, fuera del repo).
- `docs/README.md`, si se crea, se mueve o se borra un documento.
- `npm run check:docs`, si has tocado documentación. La CI lo comprueba de
  todas formas.

**Nunca**

- Inventar fechas, decisiones o motivos: si no consta, se escribe «no consta».
- Dar algo por probado o desplegado sin haberlo comprobado.
- Meter en el repo precios, facturación, notas sobre qué contarle al cliente,
  credenciales o datos de producción.
- Borrar documentación sin la aprobación de Carla.
