# Manual Técnico para el Administrador - GanttScrum Pro

Este manual proporciona las instrucciones necesarias para administrar la plataforma GanttScrum Pro, levantar los servicios, configurar la Inteligencia Artificial (Gemini) y entender la ubicación física de los archivos del sistema.

---

## 1. Arquitectura del Proyecto y Herramientas Utilizadas
La aplicación está construida sobre una arquitectura desacoplada:
*   **Backend:** FastAPI (Python 3.10+) con SQLAlchemy para el ORM y asyncpg para operaciones de base de datos asíncronas.
*   **Frontend:** Interfaz web interactiva construida en HTML5, CSS3 personalizado y JavaScript (ES6+), consumiendo la API de forma asíncrona.
*   **Base de Datos:** PostgreSQL 14+ con soporte para consultas concurrentes.
*   **Servidor de Aplicaciones:** Uvicorn como servidor ASGI para FastAPI, y Nginx como proxy inverso para servir el frontend estático y redirigir las peticiones `/api/v1` al backend.

---

## 2. Rutas y Comandos para Levantar los Servicios

En el servidor de producción actual (`10.30.0.214`), el proyecto está desplegado en la ruta:
` /opt/ganttscrum `

### A. Backend (FastAPI con Uvicorn)
El backend se ejecuta dentro de un entorno virtual de Python (`venv`).
*   **Ruta del backend:** `/opt/ganttscrum/backend`
*   **Entorno Virtual:** `/opt/ganttscrum/backend/venv`
*   **Servicio de Sistema Systemd:**
    El backend corre bajo un servicio del sistema llamado `ganttscrum.service`.
    *   **Verificar estado del servicio:**
        ```bash
        sudo systemctl status ganttscrum
        ```
    *   **Reiniciar el backend:**
        ```bash
        sudo systemctl restart ganttscrum
        ```
    *   **Detener el backend:**
        ```bash
        sudo systemctl stop ganttscrum
        ```
    *   **Iniciar el backend:**
        ```bash
        sudo systemctl start ganttscrum
        ```
    *   **Ver logs en tiempo real:**
        ```bash
        sudo journalctl -u ganttscrum -f
        ```

### B. Frontend (Servidor Web Nginx)
El frontend se compone de archivos estáticos y es servido directamente por Nginx.
*   **Ruta del frontend:** `/opt/ganttscrum/frontend`
*   **Reiniciar Nginx:**
    ```bash
    sudo systemctl restart nginx
    ```

---

## 3. Configuración y Conexión de la Inteligencia Artificial (Gemini API)

La IA (Copilot para desglosar subtareas y Generador de Informes Ejecutivos) utiliza la API de Google Gemini.

### A. Configuración en el Servidor (Backend)
Para que el backend pueda comunicarse con la API de Gemini, se requiere configurar la variable de entorno `GEMINI_API_KEY`.
1.  Obtén una API Key desde **Google AI Studio**.
2.  Edita el archivo de configuración del servicio systemd:
    ```bash
    sudo systemctl edit ganttscrum
    ```
    O bien, define la variable en el entorno o archivo `.env` en `/opt/ganttscrum/backend/.env`:
    ```env
    GEMINI_API_KEY=tu_api_key_aqui_generada_en_ai_studio
    ```
3.  Reinicia el servicio para aplicar la clave:
    ```bash
    sudo systemctl restart ganttscrum
    ```

### B. Habilitar/Deshabilitar la IA desde el Panel de Administración (Frontend)
El Administrador de la plataforma puede activar o desactivar la funcionalidad de IA globalmente desde la interfaz:
1.  Inicia sesión con tu cuenta de **Administrador**.
2.  Haz clic en el botón de **Configuración de Administrador** en la barra lateral superior.
3.  En la sección **"Asistente de IA (Gemini Copilot)"**, activa o desactiva el switch.
4.  Haz clic en **Guardar Configuración**.
    *   *Nota:* Si se desactiva, los botones de "Informe con IA" y "Sugerir con IA" se ocultarán automáticamente para todos los usuarios.

---

## 4. Ubicación de Respaldos, Informes y Archivos Adjuntos

### A. Versiones de Hoja de Ruta y Respaldos de Informes (Base de Datos)
Para asegurar el rendimiento y portabilidad de los respaldos:
*   **Versiones de la Hoja de Ruta:** Se guardan en la tabla `project_roadmap_versions` de la base de datos PostgreSQL.
*   **Respaldos de Informes (Historial HTML):** Se guardan en la tabla `project_report_versions` en la base de datos.
    *   *Nota:* No ocupan archivos planos en disco, lo que facilita que al exportar la base de datos se exporten también todos los informes y hojas de ruta históricos.

### B. Archivos Adjuntos de Tareas (Disco local)
Cuando los usuarios suben imágenes, PDFs o documentos comprimidos a una tarea del Kanban:
*   **Ruta física en el servidor:** `/opt/ganttscrum/backend/uploads/`
*   Asegúrate de que este directorio tenga permisos de escritura para el usuario que ejecuta FastAPI (`project_admin`):
    ```bash
    sudo chown -R project_admin:project_admin /opt/ganttscrum/backend/uploads
    sudo chmod -R 775 /opt/ganttscrum/backend/uploads
    ```