# Especificación de Requerimientos de Software (SRS) — GreenITESO

**Proyecto:** GreenITESO · Plataforma de Gamificación e Impacto Ambiental

**Curso:** Proyecto Integrador de Desarrollo de Software (Otoño 2026)

**Organización:** 18 integrantes organizados en 3 equipos de 6 personas

**Stack Principal Confirmado:** Backend en Python (Django / Django REST Framework) | Frontend en React (Vite) | Web Responsive Mobile-First | Progressive Web App (PWA)

**Duración del Proyecto:** 16 semanas (Entrega 1 MVP: Semana 9 | Entrega 2 Beta: Semana 13 | Entrega 3 Final: Semana 16)

**Estatus:** Versión 2.7 — Ajuste de Roles Globales de Sistema vs. Roles Contextuales de Clan

## 1. Visión General, Arquitectura Web/PWA y Alcance

GreenITESO es una plataforma web instalable como **Progressive Web App (PWA)** enfocada en dispositivos móviles y de escritorio (con enfoque *Mobile-First*), diseñada para promover comportamientos sustentables dentro de la comunidad ITESO mediante gamificación, dinámicas colaborativas (clanes/facciones) y visibilidad del impacto ecológico acumulado.

La arquitectura combina un backend unificado en **Python / Django REST Framework** con un cliente web desacoplado en **React (Vite)** estructurado como PWA. Esto permite a los miembros de la comunidad añadir GreenITESO a la pantalla de inicio de sus dispositivos móviles sin necesidad de publicar en App Store o Google Play Store, garantizando despliegue rápido, soporte offline para el caché de la interfaz (*Application Shell*) y un desarrollo sin fricciones entre los 3 equipos.

### 1.1 Jerarquía del Dominio Principal

Para garantizar consistencia, prevenir fraudes y mantener la integridad de datos entre módulos, el sistema se rige bajo la siguiente jerarquía operativa:

1. Acción Ecológica (Catálogo Maestro): Unidad atómica sustentable (ej. *Uso de bicicleta*, *Reciclaje de PET*). Solo pueden ser creadas y editadas por el Administrador. Tienen un valor predeterminado en puntos, una categoría, factores de impacto ambiental (ej. $\text{kg de CO}_2$ evitado por unidad) y un mecanismo de validación (`DECLARATIVA_BOTON`, `FOTO`).
2. **Misión:** Estructura que requiere completar una **Acción** $N$ veces (ej. *Realizar 10 viajes en bicicleta*).
3. **Campaña:** Iniciativa temporal que agrupa **Misiones**. Posee un ciclo de vida compuesto por 3 estados automáticos: `Promoción` → `En Progreso` → `Finalizada`.
    - **Campañas Globales:** Aplican a toda la comunidad ITESO. Creadas por Admin o propuestas por usuarios y aprobadas por Admin.
    - **Campañas Privadas / de Clan:** Creadas directamente por líderes de clan (`LEADER` en `ClanMembership`) para su grupo usando únicamente acciones del catálogo maestro. No requieren aprobación administrativa previa.
4. **Clan / Facción / Carrera:** Grupos de usuarios organizados para colaborar y competir.
    - **Clan Institucional (Facción):** Asignado automáticamente según la carrera o departamento del usuario (ej. *Ingeniería de Software*, *Arquitectura*, *Colaboradores*).
    - **Clan Privado:** Creado por los usuarios (ej. *Las Ranas*) para competir en grupo. Un usuario puede crear o unirse a clanes privados.

## 2. Definición de Hitos y Roadmap de Desarrollo (16 Semanas)

| **Hito / Entrega** | **Periodo** | **Alcance Funcional Clave** | **Entregables Técnicos** |
| --- | --- | --- | --- |
| **MVP 1.0 (Entrega 1)** | **Semanas 1 – 9**

*(Evaluación Sem 9)* | Auth OAuth `@iteso.mx`, Perfil Ecológico básico, CRUD Catálogo Maestro de Acciones en Django con Factores de Impacto, Registro Directo/Libre de Acciones y Hábitos Diarios (Botón y Foto $\le 5\text{ MB}$ con abono directo y auditoría posterior), Creación de Campañas Globales y Privadas, Creación/Unión a Clanes, Conteo Atómico de Puntos, PWA Manifest e interfaz React en caché. | Contratos API (OpenAPI 3.0 / Swagger), Base de Datos PostgreSQL/SQLite unificada en Django, SPA React (Vite) desplegada, Repositorios e Integración CI/CD funcionales en Staging. |
| **Beta 1.5 (Entrega 2)** | **Semanas 10 – 13**

*(Evaluación Sem 13)* | Escaneo de QR Dinámico (expiración $30\text{ s}$), Feed de Noticias (Posts Oficiales + Eventos Automáticos), Panel de Auditoría/Moderación de evidencias fotográficas para Admins con deducción atómica de puntos en rechazo, Badges/Streaks, Dashboard ITESO Impact con equivalencias ($\text{CO}_2$, agua, plástico). | Pruebas de integración E2E completadas, Cobertura de pruebas unitarias $> 70\%$, Hardening de seguridad JWT/Django, Pruebas UAT. |
| **Release Final (Entrega 3)** | **Semanas 14 – 16**

*(Evaluación Sem 16)* | Exportación de reportes de impacto ambiental (PDF/Excel), Optimización de consultas de rankings en Django ORM, Refinamiento UX/UI Mobile-First PWA, Pruebas de Carga/Estrés y Estabilización final. | Despliegue a producción, Documentación técnica final de arquitectura y retrospectiva del proyecto. |

## 3. Requerimientos Funcionales (FR) por Módulo

### Módulo 1: Identidad, Accesos y Clanes (Asignado a Equipo 2)

- **FR-AUTH-01 (Autenticación Institucional):** Inicio de sesión y registro restringido al dominio `@iteso.mx` mediante OAuth 2.0.
- **FR-AUTH-02 (Perfil Ecológico):** Visualización del historial de acciones del usuario, total de puntos acumulados, clan institucional (carrera/departamento), clan privado activo, historial de campañas finalizadas, notificaciones de auditoría y medallas obtenidas.
- **FR-AUTH-03 (Gestión de Roles Globales vs. Contextuales):**
    - **Roles Globales del Sistema (`User.role`):** `Estudiante` (`STUDENT`), `Profesor/Colaborador` (`STAFF`), `Administrador de Sustentabilidad` (`ADMIN`).
    - **Roles Contextuales de Clan (`ClanMembership.role`):** `Líder de Clan` (`LEADER`) y `Miembro Regular` (`MEMBER`). Un usuario con rol global de Estudiante puede ser `LEADER` en sus clanes privados creados sin perder su rol global de estudiante. Solo un líder
- **FR-CLAN-01 (Clanes Institucionales / Facciones):** Asignación automática o selección del clan de carrera/departamento durante el primer inicio de sesión.
- **FR-CLAN-02 (Creación de Clanes Privados):** Creación de clanes personalizados (nombre, descripción, avatar, privacidad pública/privada por invitación o clave de acceso). El usuario creador adquiere el rol contextual `LEADER` en dicho clan.
- **FR-CLAN-03 (Administración de Miembros y Borrado Lógico):** El líder del clan (`LEADER`) gestiona solicitudes de ingreso, expulsión de integrantes, asignación de Clan Privado Activo para atribución de puntos, transferencia de liderazgo y disolución del clan mediante borrado lógico (*soft delete*).

### Módulo 2: Catálogo de Acciones, Puntos y Gamificación (Asignado a Equipo 1)

- **FR-ACT-01 (Catálogo Maestro de Acciones):** El Administrador gestiona el pool maestro de acciones sustentables (Nombre, Descripción, Categoría, Puntos asignados, Límite diario/semanal de ejecución, Factor de Impacto Ecológico en $\text{kg de CO}_2 / \text{litros de agua}$, Tipo de validación: `DECLARATIVA_BOTON`, `FOTO`, `QR`).
- **FR-ACT-02 (Reglas Anti-Fraude por Frecuencia):** Bloqueo automático de registros adicionales si el usuario alcanza el límite de ejecuciones permitido en 24 horas para una acción determinada.
- **FR-VAL-01 (Registro Libre y Hábitos Diarios):** Validación instantánea de hábitos diarios simples mediante confirmación de botón (ej. usar termo reutilizable). Permite el abono de puntos individuales sin requerir estar inscrito en una campaña.
- **FR-VAL-02 (Registro con Foto Evidencia y Auditoría de Rechazo):** Carga de imagen como evidencia ($\le 5\text{ MB}$). En MVP el abono de puntos es directo con bandera `PENDIENTE_AUDITORIA`. Si el Admin rechaza posteriormente la evidencia en la auditoría, el sistema descuenta atómicamente los puntos correspondientes en el perfil individual y en los clanes afectados, generando además una notificación explicativa al usuario.
- **FR-VAL-03 (Registro por Código QR Dinámico):** (Fase Beta / Semanas 11-13) Escaneo de QR temporal generado por el sistema (válido por $30\text{ s}$ o token único) para validar presencia en eventos sustentables o puntos de acopio en campus.
- **FR-GAM-01 (Motor de Acreditación y Reversión de Puntos):** Actualización atómica e instantánea de puntos en el perfil individual del usuario y en los marcadores del clan institucional y clan privado activo, con capacidad de reajuste transaccional ante rechazos de auditoría. Los puntos son del usuario y se comparten al clan con las campañas
- **FR-GAM-02 (Tablas de Rankings / Leaderboards):** Consulta de clasificaciones en tres niveles: Personal (Top Usuarios), Clanes Privados y Clanes Institucionales (Carreras/Departamentos).
- **FR-GAM-03 (Badges e Insignias):** Otorgamiento automático de insignias al cumplir metas (ej. *10 viajes en bici*, *Primer reto de reciclaje completado*).

### Módulo 3: Campañas, Feed, Comunicaciones y Dashboards (Asignado a Equipo 3)

- **FR-CAMP-01 (Estructuración de Misiones):** Creación de misiones asociando una acción del catálogo maestro con un número $N$ de repeticiones necesarias para su cumplimiento.
- **FR-CAMP-02 (Campañas Globales):** Creación y publicación de campañas globales por el Admin con fechas de inicio, fin y estado.
- **FR-CAMP-03 (Propuestas de Campañas Globales):** Solicitud por parte de usuarios para proponer campañas globales, sujetas a aprobación o rechazo en el panel de administración.
- **FR-CAMP-04 (Campañas Privadas / de Clan):** Creación libre de campañas por líderes de clan privado (`ClanMembership.role == 'LEADER'`), utilizando únicamente misiones compuestas por acciones del catálogo maestro.
- **FR-CAMP-05 (Ciclo de Vida Automático):** Transición programada de estados: `Promoción` (solicitud/registro de miembros) $\rightarrow$ `En Progreso` (registro de acciones y cómputo de puntos) $\rightarrow$ `Finalizada` (congelamiento de marcadores).
- **FR-COMM-01 (Feed Social Dinámico):** Muro dinámico con filtro de contenido (anuncios oficiales, hitos automáticos de la comunidad y evidencias compartidas voluntariamente).
- **FR-DASH-01 (Dashboard Resumen del Usuario):** Vista rápida de puntos personales, racha activa (*streak*), misiones en curso y campañas donde participa.
- **FR-DASH-02 (Dashboard ITESO Impact):** Métricas consolidadas del campus calculadas dinámicamente según factores de impacto ($\text{CO}_2$ evitado acumulado, litros de agua ahorrados, botellas PET reutilizadas).
- **FR-DASH-03 (Panel de Administración y Moderación):** Bloqueo/Desbloqueo de usuarios, aprobación/rechazo de campañas propuestas y panel de auditoría de evidencias fotográficas con emisión de notificaciones de rechazo.

## 4. Requerimientos No Funcionales (NFR)

- **NFR-STACK-01 (Backend Python / Django):** El backend se implementará utilizando Python con Django y Django REST Framework para la exposición de APIs RESTful.
- **NFR-STACK-02 (Frontend React / Vite SPA):** La interfaz web client-side se desarrollará con **React** empaquetado con **Vite**, consumiendo los servicios RESTful expuestos por el backend Django.
- **NFR-PWA-01 (PWA Mobile-First & Alcance Conectado):** La interfaz web debe desarrollarse bajo el estándar PWA con manifiesto de aplicación (`manifest.json`), soporte para instalación en pantalla de inicio de iOS/Android y diseño 100% responsivo Mobile-First. En MVP/Beta, el soporte offline estará restringido al almacenamiento en caché de la interfaz de usuario (*Application Shell*); la ejecución de registros de acciones y consultas en tiempo real requerirá conexión a internet activa (sin sincronización en segundo plano/cola offline).
- **NFR-SEC-01 (Seguridad y Autenticación):** Uso obligatorio de HTTPS. Endpoints protegidos mediante JSON Web Tokens (JWT) verificados contra el dominio `@iteso.mx`.
- **NFR-SEC-02 (Control de Acceso RBAC):** Restricción estricta de rutas según el rol global del usuario (`STUDENT`, `STAFF`, `ADMIN`) y rol contextual de clan (`LEADER` / `MEMBER`).
- **NFR-PERF-01 (Rendimiento de APIs):** Tiempo de respuesta $\le 500\text{ ms}$ ($P_{95}$) para registro de acciones declarativas y $\le 1.5\text{ s}$ para renderizado completo de Dashboards.
- **NFR-RELI-01 (Consistencia Transaccional):** Acreditación y reversión atómica de puntos (propiedades ACID) con Django Transactions para evitar desincronización entre el perfil del usuario y las tablas agregadas de los clanes.
- **NFR-ARCH-01 (Integración de Módulos):** Contratos de API estructurados en OpenAPI 3.0 (Swagger) y compartidos entre los 3 equipos antes de implementar la lógica de negocio.

## 5. Reglas de Negocio (BR)

1. **BR-01 (Restricción de Dominio):** Únicamente se permiten registros e inicio de sesión con cuentas de correo `@iteso.mx`.
2. **BR-02 (Puntuación Unificada del Catálogo Maestro):** El valor en puntos de una Acción es inmutable dentro de las misiones y campañas. Se lee exclusivamente del Catálogo Maestro definido por el Administrador.
3. **BR-03 (Acreditación Simultánea y Atribución de Puntos):** Al validar una Acción (libre o dentro de campaña), los puntos se suman al mismo tiempo en:
    - El perfil personal del usuario.
    - El clan institucional (Carrera/Departamento) del usuario.
    - El clan privado asociado a la campaña en curso. Si es un registro libre fuera de campaña, se le acredita al **Clan Privado Activo** seleccionado por el usuario en su perfil.
4. **BR-04 (Límites de Pertenencia a Clanes):** Un usuario pertenece a **1 único Clan Institucional** (fijo) y puede pertenecer a un **máximo de 5 Clanes Privados** de manera simultánea. Solo puede ser un líder de un clan
5. **BR-05 (Límite Diario Anti-Fraude):** Alcanzado el límite diario $L$ configurado para una acción, el sistema denegará nuevos registros de dicha acción para el usuario hasta las 00:00 hrs del día siguiente.
6. **BR-06 (Campañas Privadas sin Aprobación):** Las campañas creadas por líderes de clanes privados (`ClanMembership.role == 'LEADER'`) se activan sin intervención del Admin, siempre que sus misiones pertenezcan al catálogo maestro. 
7. **BR-07 (Inmutabilidad al Finalizar Campañas):** En cuanto una campaña cambia a estado `Finalizada`, se deshabilita el registro de acciones para dicha campaña y sus posiciones se congelan permanentemente. La campaña siempre tiene fecha de finalización
8. **BR-08 (Consistencia por Abandono de Clan):** Si un usuario abandona un clan durante una campaña en progreso, los puntos aportados previamente permanecen retenidos en el acumulado histórico del clan, pero las acciones futuras ya no sumarán a ese equipo.
9. **BR-09 (Soft Delete y Preservación Histórica de Clanes):** La eliminación o disolución de un clan privado se ejecuta exclusivamente mediante borrado lógico (*soft delete*). Esto preserva la integridad referencial de los puntos históricos aportados por sus ex-integrantes en la plataforma y evita incoherencias en los marcadores globales.