# OpenCode Agent Guide: NPC Opina (NPS Survey)

This guide provides high-signal, repo-specific details to help OpenCode agents navigate, develop, and avoid mistakes in this repository.

---

## Repository Structure

The workspace is a monorepo containing multiple legacy configurations at the root, with the active modern platform housed in `/npc-new`.

*   **Active Platform (`/npc-new`)**:
    *   **Backend (`/npc-new/backend`)**: PHP Slim v4 API using PSR-4 (`App\` namespace mapping to `src/`).
    *   **Frontend (`/npc-new/frontend`)**: Svelte 5 + Vite single-page application.
    *   **Orchestration**: `/npc-new/docker-compose.yml` configures and links both services.
*   **Legacy Folders**: Directories like `legacy/`, `eticket_nps/`, `eticket_moboFacil/`, etc., are legacy PHP/HTML versions. Do not edit them unless explicitly asked.

---

## Frontend Quirks & Guidelines

*   **Svelte 5 Runes**: The frontend uses Svelte 5. Do NOT use legacy Svelte 4/3 reactive declarations (`$:`) or stores. Use runes like `$state()`, `$derived()`, and `$effect()`.
*   **Required URL Params**: The frontend expects URL query parameters to load context and validate the session:
    *   `ticket`: Required to fetch and validate survey state.
    *   `vendedor`, `fecha_ticket`, `cliente`, `email`: Context details.
    *   `c` (optional): Pre-selects the NPS grade (0-10).
*   **Design Tokens**: Follow the specification in `/legacy/DESING.md`:
    *   Accent: `--mobo` (`#0F0F12`).
    *   NPS ranges ("Semáforo"): `--nps-bad` (`#D9534F` for 0–6), `--nps-mid` (`#E8A23A` for 7–8), `--nps-good` (`#2DA771` for 9–10).
    *   Only use traffic-light colors inside the actual NPS score ranges, never as decoration.

---

## Backend Quirks & Guidelines

*   **Entry Points**: `backend/public/index.php` loads Slim. Routes are defined in `backend/src/Routes.php`.
*   **Ticket Formats**: Two ticket regex formats are accepted:
    *   POS: `/^([0-9]{6})[V|F][0-9]{1,}/`
    *   Napse: `/^([0-9]{7})[V|F][0-9]{1,}/`
*   **State / Eligibility Check**:
    *   If a ticket has empty `motivo` and `observaciones`, `/api/ticket/validate` returns `200` success (partially answered, can edit).
    *   If fully answered, it returns `403` with "El ticket ya ha sido respondido en su totalidad".
*   **Date Format**: The backend handles DD/MM/YYYY input in `fecha_ticket` and converts it to MySQL-friendly `YYYY-MM-DD` on start.

---

## Developer Commands & Environment

### Running Locally
*   **Frontend**: `npm run dev` in `/npc-new/frontend` (uses port `5173`).
*   **Backend**: Run local PHP server in `/npc-new/backend/public` (uses port `8000`).
*   **Docker**: Run `docker-compose up --build` inside `/npc-new`.

### API Configuration
*   **Local Dev**: `/npc-new/frontend/.env` sets `VITE_API_URL=http://localhost:8000`.
*   **Docker Production Build-Arg**: `VITE_API_URL` is hardcoded as `http://192.168.10.150:8081/api` in `docker-compose.yml`. Keep this in mind when modifying build/compose files.