# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Descripcion del proyecto

**Antorcha de Dios** es un sistema de gestion eclesiastica para el ministerio "Antorcha de Dios" en Argentina. Permite administrar miembros (personas), unidades organizativas (redes, celulas), usuarios con control de acceso por roles, y actividades de evangelismo (fonovisitas).

El sistema corre sobre **AppServ (Apache + PHP + MySQL)** en local y se despliega en un hosting cPanel en `antorchadedios.com.ar`.

## Ejecucion local

Servido directamente por AppServ. Abrir `http://localhost/antorcha/sistema/panel/` en el navegador. No se requiere paso de compilacion. La base de datos esta en el host remoto (`antorchadedios.com.ar`), por lo que se necesita conexion a internet incluso para desarrollo local.

## Arquitectura

El proyecto tiene dos modulos en el nivel raiz:

- `panel/` — el panel de administracion web principal (PHP, Bootstrap 5, JS vanilla)
- `api/public_html/` — placeholder vacio (solo `.htaccess` con handler PHP 8.2)

### Flujo de peticiones del panel

Todas las peticiones pasan por `panel/index.php`, que actua como controlador frontal:

1. Lee `$_GET['vista']` para determinar que vista cargar (default: `login`)
2. Verifica la sesion PHP para autenticacion
3. Segun `$_SESSION['tipo']` (`administrador`, `lider`, `maestro`), incluye el sidebar correspondiente y luego la vista solicitada desde `panel/vistas/`

La navegacion usa query strings simples: `index.php?vista=panel_persona`, `index.php?vista=panel_celula`, etc.

### Vistas con sub-gestion interna

Cada archivo en `panel/vistas/` maneja multiples modos segun `$_GET['gestion']`:
- Sin `gestion`: muestra la tabla/listado
- `gestion=registrar`: muestra el formulario de alta
- `gestion=editar&id=X`: muestra el formulario de edicion (pre-cargado con datos de BD)
- `gestion=eliminar&id=X`: muestra confirmacion de eliminacion
- `gestion=info&id=X`: muestra ficha completa (solo en persona)

### Flujo fonovisita → persona

El formulario de registro de persona acepta un `$_GET['id']` opcional que corresponde a un `fono_id`. Cuando se provee, los campos del formulario se pre-llenan con los datos de esa fonovisita. Este es el flujo de conversion: contacto evangelistico → miembro registrado.

### Control de acceso por rol

| Rol | Sidebar | Acceso |
|-----|---------|--------|
| `administrador` | `sidebar_admin.php` | Acceso completo: usuarios, personas, celulas, redes, fonovisitas |
| `lider` | `sidebar_lider.php` | Limitado (sidebar en desarrollo) |
| `maestro` | `sidebar_maestro.php` | Limitado (sidebar en desarrollo) |

### Backend (endpoints PHP)

Las operaciones CRUD son manejadas por archivos PHP dedicados en `panel/php/`, llamados mediante `fetch()` AJAX desde la capa JS. Cada endpoint recibe `$_POST['gestion_tipo']` para despachar entre las operaciones `registrar`, `actualizar` y `eliminar`.

| Endpoint | Entidad | Notas |
|----------|---------|-------|
| `panel_persona_gestion.php` | persona | CRUD completo; al registrar, busca en tabla `red` por `red_nombre` para resolver `red_lider` → `persona_lider` |
| `panel_celula_gestion.php` | celula | CRUD completo |
| `panel_red_gestion.php` | red | CRUD; `actualizar`/`eliminar` requieren gate de contrasena admin |
| `ganar_fonovisita_gestion.php` | fonovisita | CRUD; estado inicial siempre `pendiente` |
| `panel_usuario_create.php` | usuario | Crea usuarios tipo `lider` o `maestro` |
| `panel_usuario_update.php` | usuario | Actualiza datos de usuario |
| `panel_usuario_delete.php` | usuario | Elimina usuario |
| `iniciar_sesion.php` | sesion | Login |

### Utilidades compartidas (`panel/php/main.php`)

- `conexion()` — detecta entorno por `$_SERVER['HTTP_HOST']`: si es `localhost` conecta al MySQL local (`root`/`paco2009`); si no, conecta al host remoto. Cada bloque que usa PDO cierra la conexion asignando `null` al terminar.
- `limpiar_cadena($cadena)` — sanitizador de entrada: recorta, elimina barras y elimina cadenas peligrosas (palabras clave XSS/SQL). Se usa en **toda** entrada del usuario antes de cualquier procesamiento.
- `verificar_datos($filtro, $cadena)` — validador por regex; devuelve `true` si la entrada NO coincide con el patron (es decir, entrada invalida).
- `renombrar_fotos($nombre)` — sanitiza nombres de archivo para subida de fotos.
- `paginador_tablas($pagina, $n_paginas, $url, $botones)` — genera HTML de paginacion (usa clases CSS de Bulma; es codigo legado).

### Frontend (JS)

Cada entidad tiene un archivo AJAX dedicado en `panel/js/ajax-*.js`. Se adjuntan al formulario por clase CSS (ej. `.formulario-registrar-persona`) via `querySelectorAll`. Usan la Fetch API para hacer POST al endpoint PHP. Las respuestas son tokens de texto plano (ver Convenciones); el JS comprueba igualdad exacta de cadena y dispara SweetAlert2. Los archivos JS se cargan desde `panel/inc/script.php`.

Librerias incluidas localmente (sin CDN):
- Bootstrap 5 (`bootstrap5.css` / `bootstrap5.js`)
- SweetAlert2 (`sweetalert.css` / `sweetalert.js`)
- Layout del dashboard (`dashboard.css` / `dashboard.js`)

## Estructura real de la base de datos

La BD es **remota** en `antorchadedios.com.ar`. Acceso local via **SQLYog** (IP desbloqueada). No hay BD local. Credenciales en `panel/php/main.php`.

### Tabla `persona`
- PRIMARY KEY: `persona_id` int(10) AUTO_INCREMENT — puede ser asignado manualmente o auto-generado
- Todos los campos son `NOT NULL`. Los campos opcionales usan `DEFAULT ''`
- `persona_servicio varchar(255) DEFAULT ''` — libre, no obligatorio
- `persona_barrio varchar(90)` — texto libre (el formulario lo carga desde tabla `barrio`)
- `persona_lider` — se resuelve automaticamente al registrar: busca en tabla `red` por `red_nombre` y toma `red_lider`
- Campos de discipulado: `persona_abc_inicio/final`, `persona_nivel_1/2/3_inicio/final`

### Tabla `usuario`
- `usuario_id` int(10) AUTO_INCREMENT
- `usuario_tipo`: `administrador`, `lider`, `maestro`
- `usuario_lider`: nombre del lider al que pertenece (usado para maestros)
- `usuario_estado`: `activo` / (otros valores posibles)
- Contraseñas hasheadas con `PASSWORD_BCRYPT` cost 10

### Tabla `red`
- `red_id` int(10) AUTO_INCREMENT
- `red_nombre varchar(90)` — almacena el nombre del lider de red (no el nombre de la red en si)

### Tabla `celula`
- `celula_id` int(10) AUTO_INCREMENT
- `celula_nombre varchar(90)` — almacena el numero de celula como texto

### Tabla `fonovisita`
- `fono_id` int(10) AUTO_INCREMENT
- `fono_imagen varchar(255)` — columna existente para fotos, implementacion PHP pendiente
- `fono_estado`: `pendiente` / `realizado`
- `fono_fecha_registro`: generado automaticamente con `date("d-m-y")` en zona `America/Argentina/Cordoba`

### Tabla `barrio`
- Referenciada en formularios de persona y fonovisita para poblar selects
- Campos: al menos `barrio_nombre`

## Convenciones clave

- **Sanitizacion de entrada**: siempre pasar la entrada del usuario por `limpiar_cadena()` antes de cualquier uso. La inyeccion SQL se previene ademas con sentencias preparadas PDO con marcadores nombrados (`:param`).
- **Honeypot anti-bots**: los formularios de login y creacion de usuarios tienen campos ocultos. Si alguno tiene contenido, el script termina silenciosamente con `exit()`.
- **Protocolo de respuesta AJAX**: los endpoints PHP hacen `echo` de un token de texto plano. Tokens posibles: `registrar-exito`, `registrar-error`, `actualizar-exito`, `actualizar-error`, `eliminar-exito`, `eliminar-error`, `error-usuario-existente`, `error-contraseña-coincidencia`, `error-contraseña-admin`.
- **Gate de contraseña admin**: las operaciones sensibles sobre `red` requieren dos campos de contraseña que deben coincidir entre si, luego verificados con `password_verify()` contra el hash del usuario `administrador`.
- **Nombre de sesion**: `AntorchaDeDios` (definido en `panel/inc/session_start.php`, incluido en todas las paginas).

## Flujo de trabajo para cambios

| Tipo de cambio | Quien actua | Como |
|---|---|---|
| PHP / HTML / JS | Claude edita archivos | Recargar navegador y probar |
| `ALTER TABLE` | Usuario ejecuta en SQLYog | Previa verificacion de duplicados |
| Verificar estructura | Usuario | SQLYog `DESCRIBE tabla` |

**Antes de cualquier `ALTER TABLE`**: tomar backup desde cPanel > phpMyAdmin > Exportar.

## Comunicacion de cambios al usuario

Cada vez que Claude modifique un archivo, debe indicarlo claramente al final de la respuesta con el formato:

**Archivos modificados:**
- `ruta/al/archivo.php` — descripcion breve del cambio

Si hay archivos que el usuario debe subir al servidor (produccion), indicarlo explicitamente:
> Subir al servidor: `ruta/al/archivo.php`