Karma

JUX Framework incluye un sistema integrado de comentarios, valoraciones (ratings) y karma que permite recompensar a los usuarios por sus aportaciones de valor.

Índice

1. Guía del Usuario
2. Guía del Administrador
3. Guía del Desarrollador
4. Sistema de Micropagos (Lightning Network)

---

1. Guía del Usuario

¿Qué es el Karma?

El Karma es un sistema de puntos que refleja tu participación y el valor que aportas. Cuanto más contribuyas de forma positiva, más karma acumularás.

¿Cómo gano Karma?

Acción	Puntos
Iniciar sesión (1 vez al día)	+1
Publicar un post/noticia	+10
Escribir un comentario	+5
Recibir un voto positivo en tu comentario	+1
Recibir una valoración alta en tu contenido	+1 a +5
Tu respuesta marcada como solución	+8
Primer aporte en una categoría	+5
Completar tu perfil	+3
Reporte válido de contenido inapropiado	+4

¿Cómo gasto Karma?

Acción	Coste
Votar un comentario (positivo/negativo/meh)	-1
Valorar contenido (1-5 estrellas)	-1 a -5
Valorar con 0 (prohibido)	-4

¿Cómo pierdo Karma?

Acción	Penalización
Recibir voto negativo	-1
Recibir valoración baja	-1 a -2
Reporte falso	-4
Enviar demasiados votos/comentarios (flood)	-2
Intentar votar tu propio contenido	-5
Comentario eliminado por moderación	-5
Contenido marcado como spam	-10

Sistema de Comentarios

Escribir comentarios

1. Haz clic en "Nuevo comentario" para comentar en el post
2. Haz clic en "Responder" para responder a un comentario específico
3. Los comentarios soportan formato básico y bloques de código

Formato de código en comentarios

Puedes incluir código usando BBCode:

[code language=php]
echo "Hola mundo";

Lenguajes soportados: php, javascript, html, css, sql, python, java, c, cpp, y más.

Votar comentarios

• Me gusta: Indica que el comentario es útil
• No me gusta: Indica desacuerdo o contenido poco útil
• Meh: Neutral (si está habilitado)

Sistema de Valoraciones (Ratings)

Puedes valorar el contenido del 1 al 5 (o más estrellas según configuración):

• Excelente
• Muy bueno
• Bueno
• Regular
• Malo
• Prohibido (penaliza al autor)

Temas visuales

Puedes cambiar el aspecto de los comentarios usando los botones de tema:

• Default: Clásico y limpio
• Dark: Modo oscuro
• Liquid Glass: Efecto cristal moderno
• Medium: Estilo minimalista

---

2. Guía del Administrador

Panel de Moderación

Los administradores pueden:

• Aprobar: Hacer visible un comentario pendiente
• Rechazar: Ocultar un comentario inapropiado
• Editar: Modificar el contenido de cualquier comentario

Estados de comentarios

Estado	Valor	Descripción
PENDING	1	Esperando moderación
APPROVED	2	Visible públicamente
REJECTED	3	Oculto por moderación
SPAM	4	Marcado como spam

Gestión de Tablas

El framework genera y gestiona las tablas automáticamente. Accede al módulo comments en el panel de control para administrar:

• POST_COMMENTS - Comentarios de los posts
• POST_RATINGS - Valoraciones de contenido
• POST_VOTES - Votos en comentarios

Importante: No ejecutes SQL directamente en la base de datos. Usa siempre el módulo de tablas del framework para mantener la integridad del sistema de caché.

Configuración

Comentarios

Opción	Descripción
$anon	Permitir comentarios anónimos
$mod	Requerir moderación para todos
$mod_anon	Moderar solo comentarios anónimos
$max_level	Niveles máximos de anidación (default: 3)
$enable_meh	Habilitar voto "meh" (neutral)
$theme	Tema visual (default, dark, liquid-glass, medium)

Ratings

Opción	Descripción
$theme	Forma del icono (star, heart, diamond, thumbs, btc)
$size	Tamaño en píxeles [ancho, alto]

Karma

Opción	Descripción
$enabled	Activar/desactivar sistema de karma
$maxStars	Número máximo de estrellas (default: 5)

Rate Limiting

El sistema incluye protección contra flood:

• Votos: Máximo 20 por minuto
• Ratings: Máximo 10 por minuto
• Exceder el límite penaliza con -2 karma

---

3. Guía del Desarrollador

Estructura de Tablas

Las tablas se definen en _modules_/comments/ usando la clase TableMysql. El framework las crea automáticamente.

POST_COMMENTS

Campo	Tipo	Descripción
id	int(10)	ID único
module_id	int(10)	Módulo (1=Page, 2=News, 3=Blog...)
post_id	int(11)	ID del post
parent_id	int(11)	ID del comentario padre (para anidación)
user_id	int(11)	ID del usuario
user_name	varchar(100)	Nombre del usuario
comment_text	text	Contenido del comentario
status	int(1)	Estado (1=pending, 2=approved, 3=rejected, 4=spam)
votes_up/down/meh	int(11)	Contadores de votos

POST_RATINGS

Campo	Tipo	Descripción
id	int(11)	ID único
module_id	int(11)	Módulo
post_id	int(11)	ID del post
user_id	int(11)	ID del votante
rating	int(11)	Valor del rating (0 a maxStars)

POST_VOTES

Campo	Tipo	Descripción
id	int(10)	ID único
comment_id	int(11)	ID del comentario votado
user_id	int(11)	ID del votante
vote_type	int(1)	Tipo (0=unset, 1=up, 2=down, 3=meh)

Integración de Comentarios

Mostrar comentarios en una página

// En tu módulo (ej: news/index.php)
Comments::$module = 2;  // 2 = News
Comments::$url = 'news/ajax';
Comments::$admin = $juxACL->hasPermission('admin_comments');
Comments::$theme = 'theme-medium';
Comments::show($post_id);

Endpoint AJAX

// En tu archivo ajax (ej: news/ajax.php)
include(SCRIPT_DIR_MODULES.'/comments/ajax_comments.php');

Integración de Ratings

Rating::$module = 2;
Rating::$url = 'news/ajax';
Rating::$theme = 'star';  // star, heart, diamond, thumbs, btc
Rating::$size = [30, 30];
Rating::show($post_id);

Sistema de Karma - Ejemplos de Uso

Recompensar acciones

// Al crear un post
Karma::rewardPostCreated($_SESSION['userid']);

// Al publicar un comentario (ya integrado en Comments::saveComment)
Karma::rewardCommentPosted($_SESSION['userid']);

// Al completar el perfil
Karma::rewardProfileCompleted($_SESSION['userid']);

// Al verificar email
Karma::addPoints($_SESSION['userid'], Karma::EMAIL_VERIFIED);

// Al subir avatar
Karma::addPoints($_SESSION['userid'], Karma::AVATAR_UPLOADED);

// Primera contribución en una categoría
Karma::rewardFirstCategoryPost($_SESSION['userid']);

// Respuesta marcada como solución
Karma::rewardAcceptedSolution($_SESSION['userid']);

// Propinas (Lightning Network)
Karma::addPoints($author_id, Karma::TIP_RECEIVED);
Karma::addPoints($tipper_id, Karma::TIP_GIVEN);

Penalizar acciones

// Reporte falso
Karma::penalizeFalseReport($_SESSION['userid']);

// Flood detectado (ya integrado con RateLimiter)
Karma::penalizeFlooding($_SESSION['userid']);

// Intento de auto-voto
Karma::penalizeSelfVoteDetected($_SESSION['userid']);

// Comentario eliminado por moderación
Karma::penalizeCommentRemoved($comment_author_id);

// Contenido marcado como spam
Karma::penalizeSpamContent($_SESSION['userid']);

Verificar y gastar karma

// Verificar si puede gastar
if (Karma::canSpend($_SESSION['userid'], 5)) {
    // Puede gastar 5 puntos
}

// Gastar puntos (retorna false si no tiene suficiente)
if (Karma::spendPoints($_SESSION['userid'], 3)) {
    // Gasto exitoso
}

// Obtener karma actual
$score = Karma::getUserScore($_SESSION['userid']);

Aplicar rating con karma

$result = Karma::applyRating(
    $voter_id,           // ID del votante
    $post_owner_id,      // ID del autor del post
    $new_rating,         // Nuevo rating (0-5)
    $previous_rating     // Rating anterior (null si es primero)
);

if ($result['error']) {
    echo $result['msg'];
} else {
    echo "Coste: " . $result['cost'];
    echo "Devolución: " . $result['refund'];
}

Bonus de Login Diario

El bonus se aplica automáticamente en Login::updateLastLogin() usando el campo user_last_login de la tabla de usuarios:

// Solo da +1 punto si el último login fue en un día diferente
$dia_ultimo_login = date('Y-m-d', $ultimo_login);
$karma_bonus = ($dia_ultimo_login !== $hoy) ? 1 : 0;

Mostrar Karma del Usuario

// En el frontend
Karma::showUserScore();  // Muestra badge fijo en esquina

// Actualizar vía AJAX después de una acción
Karma::updateUserScore();  // Inyecta script para actualizar #user_score

Hooks Disponibles

Hook	Cuándo usarlo
Karma::rewardPostCreated($user_id)	Al publicar contenido
Karma::rewardCommentPosted($user_id)	Al comentar
Karma::rewardProfileCompleted($user_id)	Al completar perfil
Karma::rewardFirstCategoryPost($user_id)	Primer post en categoría
Karma::rewardAcceptedSolution($user_id)	Respuesta aceptada
Karma::rewardValidReport($user_id)	Reporte confirmado válido
Karma::penalizeFalseReport($user_id)	Reporte falso
Karma::penalizeFlooding($user_id)	Rate limit excedido
Karma::penalizeSelfVoteDetected($user_id)	Auto-voto detectado
Karma::penalizeCommentRemoved($user_id)	Comentario moderado
Karma::penalizeSpamContent($user_id)	Contenido spam
Karma::applyRating(...)	Al valorar contenido
Karma::applyCommentVote(...)	Al votar comentario

Constantes de Puntos

// Ganancias
Karma::POST_CREATED        = 10;
Karma::COMMENT_POSTED      = 5;
Karma::POST_UPVOTED        = 1;
Karma::PROFILE_COMPLETED   = 3;
Karma::ACCEPTED_SOLUTION   = 8;
Karma::VALID_REPORT        = 4;
Karma::DAILY_LOGIN         = 1;
Karma::EMAIL_VERIFIED      = 5;
Karma::AVATAR_UPLOADED     = 2;
Karma::TIP_RECEIVED        = 5;
Karma::TIP_GIVEN           = 2;

// Pérdidas
Karma::POST_DOWNVOTED          = -1;
Karma::PENALTY_FALSE_REPORT    = -4;
Karma::PENALTY_FLOOD           = -2;
Karma::PENALTY_SELF_VOTE       = -5;
Karma::PENALTY_COMMENT_REMOVED = -5;
Karma::PENALTY_SPAM_CONTENT    = -10;

// Costes
Karma::COMMENT_VOTE_COST = 1;
Karma::RATING_ZERO_COST  = 4;
Karma::RATING_ZERO_IMPACT = -2;

---

4. Sistema de Micropagos (Lightning Network)

⚡ Funcionalidad en desarrollo

JUX Framework incluye integración con Lightning Network (Bitcoin) para micropagos, permitiendo:

Propinas a los autores

• Los usuarios pueden enviar propinas (tips) en satoshis a los autores de contenido
• Cada autor tiene su propia cuenta donde se acumulan las propinas recibidas
• Desde el perfil de usuario, los autores pueden retirar sus satoshis a su wallet personal

Configuración de comisiones

El administrador puede configurar:

• 100% para autores: Todas las propinas van íntegras al autor
• Porcentaje para la web: Un pequeño % se destina al mantenimiento de la plataforma (configurable)

Comprar Karma con Satoshis

El sistema permite configurar la compra de puntos de karma con satoshis:

• Ratio por defecto: 1 satoshi = 1 punto de karma
• Permite a usuarios nuevos o con poco karma participar activamente
• Configurable por el administrador

Ejemplo de uso (propina)

// Al recibir una propina confirmada
Karma::addPoints($author_id, Karma::TIP_RECEIVED);  // +5 karma al autor
Karma::addPoints($tipper_id, Karma::TIP_GIVEN);     // +2 karma al que da propina

// Registrar la transacción
LightningPayments::recordTip($invoice_id, $author_id, $amount_sats);

Integración BTCPay Server

El sistema utiliza BTCPay Server para gestionar las invoices de Lightning Network:

// Crear invoice para propina
$invoice = BTCPay::createInvoice([
    'amount' => $amount_sats / 100000000,  // Convertir a BTC
    'currency' => 'BTC',
    'metadata' => [
        'type' => 'tip',
        'articleId' => $post_id,
        'authorId' => $author_id
    ]
]);

---

Sobre JUX Framework

JUX Framework es un framework PHP open source para desarrollo web rápido. Esta documentación cubre el sistema de comentarios, ratings y karma. La documentación completa del framework estará disponible próximamente.

Versión: 3.0
Licencia: Open Source