docs: agregar CLAUDE.md, CONTEXT.md y project.yaml del proyecto

Author: devsart95

CLAUDE.md

@@ -0,0 +1,55 @@
+# AyudaPy — Plataforma de ayuda solidaria geolocalizada
+
+## Stack
+- Python 3.8+ / Django 4.2 / PostGIS (PostgreSQL + extensión geoespacial)
+- Django REST Framework (API v1 con GeoJSON)
+- Leaflet + GeoPy (Nominatim) para mapas y geocoding
+- django-pipeline (CSS/JS con yuglify)
+- django-simple-history (auditoría)
+- Dockerizado: app (Django :8000) + db (PostGIS :5432)
+
+## Estructura
+- `core/` — Solicitudes de ayuda (HelpRequest), categorías, FAQ, devices
+- `org/` — Organizaciones, centros de donación, perfiles voluntarios
+- `conf/` — Settings, URLs, API URLs, WSGI
+- `templates/` — Templates Django (28 HTML)
+- `static/` — CSS, JS, imágenes, fuentes, libs (leaflet, bulma, apexcharts)
+- `docker/` — Dockerfile + wait-for-db.sh
+
+## Comandos
+```bash
+# Docker
+cp conf/.env.example conf/.env
+docker-compose up -d --build
+docker-compose exec app ./manage.py migrate
+docker-compose exec app ./manage.py compilemessages
+
+# Local
+python3 -m venv env && source env/bin/activate
+pip install -r requirements.txt && npm -g install yuglify
+./manage.py migrate && ./manage.py runserver
+
+# i18n
+django-admin makemessages --ignore=env -l es
+django-admin compilemessages
+```
+
+## Convenciones
+- Rama principal para PRs: `dev` (no master)
+- Admin real: `/jara/` — `/admin/` es honeypot
+- Idioma: español (es), timezone America/Asuncion
+- API base: `/api/v1/`
+- Tests: `core/tests.py`, `org/tests.py` (actualmente vacíos)
+
+## Rutas clave
+```
+/                    → home (mapa principal)
+/solicitar           → crear solicitud
+/pedidos             → listar por ciudad
+/pedidos/<id>        → detalle solicitud
+/donar               → requiere permisos
+/ceder               → crear centro donación
+/donaciones          → listar donaciones
+/stats               → dashboard (login required)
+/api/v1/             → REST API
+```

CONTEXT.md

@@ -0,0 +1,140 @@
+# CONTEXT — AyudaPy
+
+## Estado actual
+- Proyecto en mantenimiento — features congeladas desde 2020
+- Actividad reciente: solo bumps de seguridad (Dependabot)
+- 2 PRs de seguridad pendientes de merge (#376 Django 4.2.28, #377 Pillow 12.1.1)
+- 27 issues abiertos (todos de abril-mayo 2020)
+- Tests vacíos (core/tests.py, org/tests.py)
+
+## Auditoría de seguridad (2026-03-24)
+
+### CRÍTICOS
+1. **Teléfonos expuestos vía API sin auth** — core/serializers.py:10, org/serializers.py:9,15. GET público retorna phone de todos los solicitantes
+2. **API sin rate limiting ni permisos** — REST_FRAMEWORK no define DEFAULT_PERMISSION_CLASSES ni DEFAULT_THROTTLE_CLASSES. Todos los endpoints abiertos incluyendo CRUD de devices
+3. **ALLOWED_HOSTS = ['*']** — conf/settings.py:29. Host Header Injection. Sin SECURE_HSTS, SESSION_COOKIE_SECURE, CSRF_COOKIE_SECURE, CSRF_TRUSTED_ORIGINS
+
+### ALTOS
+4. **DEBUG_PROPAGATE_EXCEPTIONS = True** — conf/settings.py:31. Stack traces expuestos
+5. **Geocoding síncrono sin timeout en save()** — core/models.py:125-140, org/models.py:48-60,111-123,165-177. Bloquea requests, DoS vector. En org/ no tiene try/except
+6. **api_settings no importado** — core/api.py:149. NameError en POST /api/v1/devices/
+7. **Docker EOL** — python:3.9-buster, sin multi-stage, sin user no-root, sin healthcheck
+
+### MEDIOS
+8. Queries sin límite — core/views.py:165 (TODO del autor)
+9. Middleware silencia errores — core/middleware.py:27-32 (except: pass)
+10. device.save(device) bug — core/middleware.py:92
+11. Headers seguridad ausentes (HSTS, CSP, cookie flags)
+12. Dependencias antiguas (geopy 1.21, django-filter 2.4, django-environ 0.4.5)
+
+## Auditoría frontend (2026-03-24)
+
+### CRÍTICOS
+1. **XSS vía innerHTML** — templates/help_request/create.html:75-79 (API geocoding sin sanitizar), static/scripts/list.js:204-216 y list-donation.js:193-215 (popup markers sin sanitizar). sanitizeHTML() existe en table-view.js pero no se usa
+2. **Validación client-side insuficiente** — create.html:151-172, sin feedback visual, sin prevención de doble submit
+
+### ALTOS
+3. **Accesibilidad** — base.html sin lang="es", 6+ imágenes sin alt, `<p onclick>` en post.html (no accesible), sin aria-required/aria-invalid en forms
+4. **JS duplicado 95%** — list.js (316 LOC) y list-donation.js (305 LOC) son copy-paste
+5. **Librerías deprecated** — Bulma 0.8.0 (2020), Moment.js 2.24.0 (deprecated), BulmaJS 0.10.3 (2019)
+6. **Performance** — ~15-20 HTTP requests, ~300KB+, sin lazy loading, scripts sin async/defer, Leaflet cargado en páginas sin mapa, 130 líneas CSS inline en base.html
+
+### MEDIOS
+7. JS legacy — charCode deprecated (list.js:75), console.log en prod (list.js:123), Date.prototype mutado (list.js:159), variable global implícita (create.html:91)
+8. Sin debounce en búsqueda — list.js:174, cada Enter dispara API call sin throttle
+
+## Plan de contribución
+
+### Fase 1 — Seguridad (completada 2026-03-24)
+- [x] Excluir `phone` de serializers REST (core + org) y de search_fields en API
+- [x] Agregar DEFAULT_PERMISSION_CLASSES y DEFAULT_THROTTLE_CLASSES (100/h anon, 300/h user)
+- [x] Configurar ALLOWED_HOSTS via env (default localhost)
+- [x] Remover DEBUG_PROPAGATE_EXCEPTIONS
+- [x] Agregar timeout=5 a Nominatim + try/except en org/models.py (3 modelos) y core/models.py
+- [x] Fix import api_settings en core/api.py
+- [x] Agregar headers de seguridad (HSTS, SESSION/CSRF_COOKIE_SECURE, X_FRAME_OPTIONS=DENY)
+- [x] Fix search_fields en org/api.py ('title' no existe en DonationCenter → 'name')
+- [x] Fix BaseResource.save() accedía a self.phone sin tenerlo (hasattr check)
+- [x] Fix device.save(device) → device.save() en middleware
+
+### Fase 1b — Seguridad frontend (completada 2026-03-24)
+- [x] Sanitizar innerHTML: escapeHTML() en create.html (geocoding API), sanitizeHTML() exportada desde table-view.js y usada en popups de list.js y list-donation.js
+- [x] Prevención de doble submit: onsubmit="return checkRequestForm()" en help_request/create.html y donation_center/create.html
+- [x] Remover console.log con coordenadas en list.js y list-donation.js
+- [x] encodeURIComponent en URL de geocoding (create.html)
+- [x] parseInt en pk de popups (list.js, list-donation.js) para evitar inyección en href
+
+### Fase 2 — Infraestructura
+- [ ] Actualizar Docker: python:3.12-slim, multi-stage, no-root user, healthchecks
+- [ ] Actualizar dependencias antiguas (geopy 2.x, django-filter 24.x)
+- [ ] Fix middleware silencioso (except: pass sin logging)
+- [ ] Mergear PRs pendientes de seguridad (#376, #377)
+
+### Fase 3 — Tests
+- [ ] Tests para modelos (HelpRequest, DonationCenter)
+- [ ] Tests para API endpoints
+- [ ] Tests para formularios y vistas
+
+### Fase 4 — Frontend cleanup (parcial 2026-03-24)
+- [x] Agregar lang="es" a `<html>` en base.html
+- [x] Alt text en todas las imágenes (logo, footer, details thumbnail, phone img)
+- [x] Convertir `<p onclick>` a `<button type="button">` con aria-label en post.html
+- [x] Fix login.html class duplicado (Bulma+Bootstrap → solo Bulma)
+- [x] Remover borde debug verde en list.html y donation_center/list.html
+- [x] Agregar defer a scripts bloqueantes (fontawesome, bulmajs, moment)
+- [x] Aria-labels: loading indicator (role=status), cities input, role=search en dropdowns
+- [x] Error handling en fetch (catch para ocultar spinner en list.js y list-donation.js)
+- [x] Aria-label en delete button de notificaciones (details.html)
+- [ ] Refactorizar list.js y list-donation.js en módulo compartido
+- [ ] Reemplazar Moment.js por Day.js o formateo nativo
+- [ ] Agregar loading="lazy" a imágenes
+- [ ] Mover CSS inline de base.html a archivo separado
+- [ ] Agregar debounce a búsqueda
+- [ ] Fix charCode → e.key, Date.prototype, variable global
+- [ ] Extraer colores hardcoded a variables CSS
+- [ ] i18n: strings hardcoded en donation_center templates
+
+### Fase 5 — Features (issues abiertos prioritarios)
+- [ ] #295 Filtro por departamento/provincia
+- [ ] #241 Categorías en API
+- [ ] #157 Expiración de pedidos
+- [ ] #167 Ciudades vía AJAX
+- [ ] #288 Fix ciudades con error 502
+
+## Issues abiertos (27 total, todos de abril-mayo 2020)
+
+### Critical path
+- #295 Filtro por departamento/provincia
+- #182 Campos uso interno para users logueados
+- #76 Registro de usuario
+
+### Features
+- #250 POST y AUTH en API | #241 Categorías en API | #272 Buscar por id/name
+- #257 Sauron Mode (zoom sin límite auth) | #210 Leaflet.awesome-markers
+- #229 Solo thumbnails | #200 Migrar a S3/Spaces | #197 CI/CD Jenkins
+- #167 Ciudades vía AJAX | #157 Expiración pedidos | #150 Filtro fechas
+- #145 db_index en User/Device | #127 Mis Pedidos | #126 Mi Perfil
+- #74 Columnas status HelpRequest | #68 Lista pendientes/asistidos
+- #25 Filtro ventana temporal | #165 2FA admin | #123 Consultas BD internas
+
+### Bugs
+- #288 Ciudades con error 502 (~15 ciudades)
+- #270 Ubicación no se borra en mapa
+- #184 Error crear usuarios en admin
+
+### Good first issue
+- #294 Traducir I18N-GUIDE a español
+- #272 Agregar id/name a búsqueda
+- #241 Categorías en API
+
+### Descartados
+- #64 Ollas populares (wontfix) | #33 Campo confiable (duplicate)
+
+### PRs abiertos
+- #377 Bump Pillow 12.1.1 (seguridad) | #376 Bump Django 4.2.28 (seguridad)
+- #281 Ollas populares (duplicate) | #268 Terser JS minifier (draft)
+- #166 2FA admin (bugs pendientes)
+
+## Pendiente
+- Contactar al owner (melizeche) antes de PRs grandes
+- Verificar si hay ambiente de staging/producción activo

project.yaml

@@ -0,0 +1,30 @@
+name: ayudapy
+description: Plataforma humanitaria de ayuda solidaria geolocalizada — Paraguay
+tier: contribucion
+status: auditoria
+
+stack:
+  language: python
+  framework: django-4.2
+  database: postgresql-postgis
+  api: django-rest-framework
+  maps: leaflet-geopy
+  containerization: docker-compose
+
+repo:
+  origin: https://github.com/melizeche/ayudapy
+  branch: dev
+  license: AGPL-3.0
+
+features:
+  - solicitudes-ayuda-geolocalizadas
+  - api-rest-geojson
+  - centros-donacion
+  - busqueda-fulltext-es
+  - i18n-es
+  - django-admin-honeypot
+
+integraciones:
+  - nominatim-geocoding
+  - leaflet-maps
+  - jenkins-ci