PROJECT_STRUCTURE.txt

ChronoBot - Automatización de Fichaje en Bizneo
================================================

Estructura del Proyecto:

biz_scrap/
│
├── 📄 .gitignore                      # Archivos ignorados por Git (incluye config.json)
├── 📄 requirements.txt                # Dependencias Python
├── 📄 setup.bat                       # Script de instalación automática Windows
│
├── 📖 README.md                       # Documentación completa del proyecto
├── 📖 INSTALL.md                      # Guía de instalación paso a paso
├── 📖 QUICK_START.md                  # Guía de inicio rápido (5 minutos)
├── 📄 PROJECT_STRUCTURE.txt           # Este archivo
│
├── ⚙️ config.json.sample              # Plantilla de configuración (copiar a config.json)
├── 🔒 config.json                     # Configuración con credenciales (NO subir a Git)
│
├── 🐍 run_manual.py                   # Script para ejecución manual inmediata
├── 🐍 run_service.py                  # Script para ejecución como servicio permanente
├── 🐍 install_windows_service.py      # Instalador de servicio de Windows
├── 🐍 test_connection.py              # Test de conexión y credenciales
│
├── 📁 src/                            # Código fuente principal
│   ├── __init__.py                    # Inicializador del módulo
│   ├── utils.py                       # Utilidades: config, logs, festivos
│   ├── scraper.py                     # Lógica de Playwright (login, clic)
│   └── scheduler.py                   # Programador de tareas (horarios)
│
├── 📁 days/                           # Gestión de días laborables
│   └── holidays.json                  # Lista de festivos (editable)
│
├── 📁 logs/                           # Logs de ejecución (auto-generado)
│   └── chrono_bot.log                 # Log principal con historial
│
├── 📁 screenshots/                    # Capturas de pantalla (auto-generado)
│   ├── before_login_TIMESTAMP.png
│   ├── after_login_TIMESTAMP.png
│   └── after_click_TIMESTAMP.png
│
└── 📁 playwright-state/               # Estado del navegador (auto-generado)
    └── state.json                     # Cookies y sesión guardada


Flujo de Archivos:
==================

1. INSTALACIÓN
   └── setup.bat
       └── Crea venv/
       └── Instala requirements.txt
       └── Instala Playwright
       └── Crea config.json desde config.json.sample

2. CONFIGURACIÓN
   └── config.json (editar credenciales)
   └── days/holidays.json (editar festivos)

3. TESTING
   └── test_connection.py
       └── Verifica acceso a plataforma
       └── Guarda capturas en screenshots/
   
   └── run_manual.py
       └── Ejecuta una vez inmediatamente
       └── Guarda logs en logs/
       └── Guarda estado en playwright-state/

4. PRODUCCIÓN
   └── run_service.py
       └── Servicio en primer plano
       └── Ctrl+C para detener
   
   └── install_windows_service.py
       └── Instala como servicio de Windows
       └── Se ejecuta al iniciar el sistema


Módulos Python:
===============

src/utils.py
    ├── Config()                       # Gestión de configuración
    ├── HolidayChecker()               # Verificación de festivos
    ├── setup_logging()                # Configuración de logs
    └── ensure_directories()           # Creación de directorios

src/scraper.py
    └── BizneoScraper()
        ├── run()                      # Flujo completo
        ├── _login()                   # Login en plataforma
        ├── _is_logged_in()            # Verificar sesión
        ├── _click_chrono_button()     # Clic en botón
        └── _take_screenshot()         # Captura de pantalla

src/scheduler.py
    └── ChronoScheduler()
        ├── setup_schedule()           # Configurar horarios
        ├── execute_morning_task()     # Tarea de mañana
        ├── execute_evening_task()     # Tarea de tarde
        └── run()                      # Loop principal


Configuración:
==============

config.json
    ├── credentials                    # Email y contraseña
    ├── schedule                       # Horarios de ejecución
    │   ├── morning                    # 08:30 - 09:10
    │   └── evening                    # 18:00 - 19:00
    ├── platform                       # URL y timeout
    ├── browser                        # Headless, estado
    └── logging                        # Logs y nivel


Seguridad:
==========

✅ config.json está en .gitignore
✅ No se sube a GitHub
✅ playwright-state/ tampoco se sube
✅ logs/ y screenshots/ tampoco se suben

❌ NUNCA compartas config.json
❌ NUNCA subas credenciales a repositorios


Comandos Principales:
=====================

# Instalación
.\setup.bat

# Testing
python test_connection.py
python run_manual.py

# Producción
python run_service.py

# Servicio Windows (como Administrador)
python install_windows_service.py install
net start ChronoBotService
net stop ChronoBotService
python install_windows_service.py uninstall

# Ver logs
Get-Content logs\chrono_bot.log -Tail 50
Get-Content logs\chrono_bot.log -Wait


Estado de Archivos en Git:
===========================

✅ SUBIR A GIT:
   - Todos los archivos .py
   - requirements.txt
   - config.json.sample
   - days/holidays.json
   - README.md y documentación
   - .gitignore

❌ NO SUBIR A GIT (protegidos por .gitignore):
   - config.json (credenciales)
   - logs/ (logs de ejecución)
   - screenshots/ (capturas)
   - playwright-state/ (sesiones)
   - venv/ (entorno virtual)
   - __pycache__/ (caché Python)