bulltrackers-module 1.0.733 → 1.0.734

package/functions/computation-system-v2/rules/rankings.js

@@ -0,0 +1,655 @@
+/**
+ * @fileoverview Rankings Business Rules
+ * 
+ * For extracting and calculating metrics from pi_rankings data.
+ * The rankings_data JSON contains comprehensive investor metrics from eToro.
+ * 
+ * Usage in computation:
+ * ```javascript
+ * const rankingsData = rules.rankings.extractRankingsData(row);
+ * const riskScore = rules.rankings.getRiskScore(rankingsData);
+ * const tier = rules.rankings.getAUMTier(rankingsData);
+ * ```
+ */
+
+// =============================================================================
+// DATA EXTRACTION
+// =============================================================================
+
+/**
+ * Extract rankings_data from a pi_rankings row.
+ * Handles both string JSON and parsed object.
+ * 
+ * @param {Object} row - pi_rankings row
+ * @returns {Object|null} Parsed rankings data
+ */
+function extractRankingsData(row) {
+    if (!row) return null;
+    
+    let data = row.rankings_data;
+    
+    if (typeof data === 'string') {
+        try {
+            data = JSON.parse(data);
+        } catch (e) {
+            return null;
+        }
+    }
+    
+    return data || null;
+}
+
+/**
+ * Get the PI ID from a rankings row.
+ * @param {Object} row - pi_rankings row
+ * @returns {string|number|null}
+ */
+function getPiId(row) {
+    return row?.pi_id || row?.CustomerId || null;
+}
+
+/**
+ * Get the username from a rankings row.
+ * @param {Object} row - pi_rankings row
+ * @returns {string|null}
+ */
+function getUsername(row) {
+    return row?.username || row?.UserName || extractRankingsData(row)?.UserName || null;
+}
+
+// =============================================================================
+// RISK METRICS
+// =============================================================================
+
+/**
+ * Get the risk score (0-10 integer).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getRiskScore(data) {
+    return data?.RiskScore ?? 0;
+}
+
+/**
+ * Get max daily risk score.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getMaxDailyRiskScore(data) {
+    return data?.MaxDailyRiskScore ?? 0;
+}
+
+/**
+ * Get max monthly risk score.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getMaxMonthlyRiskScore(data) {
+    return data?.MaxMonthlyRiskScore ?? 0;
+}
+
+/**
+ * Get daily drawdown percentage (negative number).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getDailyDrawdown(data) {
+    return data?.DailyDD ?? 0;
+}
+
+/**
+ * Get weekly drawdown percentage (negative number).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getWeeklyDrawdown(data) {
+    return data?.WeeklyDD ?? 0;
+}
+
+/**
+ * Get peak to valley (max drawdown).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getPeakToValley(data) {
+    return data?.PeakToValley ?? 0;
+}
+
+/**
+ * Categorize risk score into a tier.
+ * @param {number} riskScore - Risk score 0-10
+ * @returns {string} 'low' | 'medium' | 'high' | 'very_high'
+ */
+function getRiskTier(riskScore) {
+    if (riskScore <= 3) return 'low';
+    if (riskScore <= 5) return 'medium';
+    if (riskScore <= 7) return 'high';
+    return 'very_high';
+}
+
+// =============================================================================
+// PERFORMANCE METRICS
+// =============================================================================
+
+/**
+ * Get total gain percentage (2 full years + current year).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getTotalGain(data) {
+    return data?.Gain ?? 0;
+}
+
+/**
+ * Get daily gain percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getDailyGain(data) {
+    return data?.DailyGain ?? 0;
+}
+
+/**
+ * Get this week's gain percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getWeeklyGain(data) {
+    return data?.ThisWeekGain ?? 0;
+}
+
+/**
+ * Get win ratio (0-100).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getWinRatio(data) {
+    return data?.WinRatio ?? 0;
+}
+
+/**
+ * Get profitable weeks percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getProfitableWeeksPct(data) {
+    return data?.ProfitableWeeksPct ?? 0;
+}
+
+/**
+ * Get profitable months percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getProfitableMonthsPct(data) {
+    return data?.ProfitableMonthsPct ?? 0;
+}
+
+/**
+ * Get copiers gain (performance of copiers).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getCopiersGain(data) {
+    return data?.CopiersGain ?? 0;
+}
+
+// =============================================================================
+// AUM & COPIERS
+// =============================================================================
+
+/**
+ * Get AUM (Assets Under Management) in USD.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getAUM(data) {
+    return data?.AUMValue ?? 0;
+}
+
+/**
+ * Get AUM tier (1-5).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getAUMTier(data) {
+    return data?.AUMTier ?? 0;
+}
+
+/**
+ * Get AUM tier description.
+ * @param {Object} data - rankings_data object
+ * @returns {string}
+ */
+function getAUMTierDesc(data) {
+    return data?.AUMTierDesc || 'Unknown';
+}
+
+/**
+ * Get current copiers count.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getCopiers(data) {
+    return data?.Copiers ?? 0;
+}
+
+/**
+ * Get baseline copiers count.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getBaselineCopiers(data) {
+    return data?.BaseLineCopiers ?? 0;
+}
+
+/**
+ * Calculate copier change from baseline.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getCopierChange(data) {
+    const current = getCopiers(data);
+    const baseline = getBaselineCopiers(data);
+    return current - baseline;
+}
+
+/**
+ * Calculate copier change percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getCopierChangePct(data) {
+    const baseline = getBaselineCopiers(data);
+    if (baseline === 0) return 0;
+    return ((getCopiers(data) - baseline) / baseline) * 100;
+}
+
+// =============================================================================
+// TRADING STYLE
+// =============================================================================
+
+/**
+ * Get exposure percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getExposure(data) {
+    return data?.Exposure ?? 0;
+}
+
+/**
+ * Get long position percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getLongPosPct(data) {
+    return data?.LongPosPct ?? 0;
+}
+
+/**
+ * Get short position percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getShortPosPct(data) {
+    return 100 - (data?.LongPosPct ?? 100);
+}
+
+/**
+ * Get average position size percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getAvgPosSize(data) {
+    return data?.AvgPosSize ?? 0;
+}
+
+/**
+ * Get total trades count.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getTotalTrades(data) {
+    return data?.Trades ?? 0;
+}
+
+/**
+ * Get total traded instruments count.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getTotalInstruments(data) {
+    return data?.TotalTradedInstruments ?? 0;
+}
+
+/**
+ * Get leverage breakdown.
+ * @param {Object} data - rankings_data object
+ * @returns {Object} { low, medium, high }
+ */
+function getLeverageBreakdown(data) {
+    return {
+        low: data?.LowLeveragePct ?? 0,
+        medium: data?.MediumLeveragePct ?? 0,
+        high: data?.HighLeveragePct ?? 0
+    };
+}
+
+/**
+ * Determine primary trading style.
+ * @param {Object} data - rankings_data object
+ * @returns {string}
+ */
+function getTradingStyle(data) {
+    const longPct = getLongPosPct(data);
+    const leverage = getLeverageBreakdown(data);
+    const trades = getTotalTrades(data);
+    const instruments = getTotalInstruments(data);
+    
+    // Determine direction bias
+    let directionStyle = 'balanced';
+    if (longPct >= 80) directionStyle = 'long-only';
+    else if (longPct <= 20) directionStyle = 'short-focused';
+    
+    // Determine leverage style
+    let leverageStyle = 'conservative';
+    if (leverage.high > 30) leverageStyle = 'aggressive';
+    else if (leverage.medium > 40) leverageStyle = 'moderate';
+    
+    // Determine diversification
+    let diversification = 'concentrated';
+    if (instruments >= 20) diversification = 'diversified';
+    else if (instruments >= 10) diversification = 'moderate';
+    
+    return `${directionStyle}, ${leverageStyle}, ${diversification}`;
+}
+
+// =============================================================================
+// TOP ASSET INFO
+// =============================================================================
+
+/**
+ * Get top traded instrument ID.
+ * @param {Object} data - rankings_data object
+ * @returns {number|null}
+ */
+function getTopInstrumentId(data) {
+    return data?.TopTradedInstrumentId || null;
+}
+
+/**
+ * Get top traded instrument percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getTopInstrumentPct(data) {
+    return data?.TopTradedInstrumentPct ?? 0;
+}
+
+/**
+ * Get top traded asset class ID.
+ * @param {Object} data - rankings_data object
+ * @returns {number|null}
+ */
+function getTopAssetClassId(data) {
+    return data?.TopTradedAssetClassId || null;
+}
+
+/**
+ * Get tags array.
+ * @param {Object} data - rankings_data object
+ * @returns {number[]}
+ */
+function getTags(data) {
+    return data?.Tags || [];
+}
+
+// =============================================================================
+// ACTIVITY & STATUS
+// =============================================================================
+
+/**
+ * Get active weeks count.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getActiveWeeks(data) {
+    return data?.ActiveWeeks ?? 0;
+}
+
+/**
+ * Get active weeks percentage.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getActiveWeeksPct(data) {
+    return data?.ActiveWeeksPct ?? 0;
+}
+
+/**
+ * Get weeks since registration.
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function getWeeksSinceRegistration(data) {
+    return data?.WeeksSinceRegistration ?? 0;
+}
+
+/**
+ * Get first activity date.
+ * @param {Object} data - rankings_data object
+ * @returns {Date|null}
+ */
+function getFirstActivity(data) {
+    return data?.FirstActivity ? new Date(data.FirstActivity) : null;
+}
+
+/**
+ * Get last activity date.
+ * @param {Object} data - rankings_data object
+ * @returns {Date|null}
+ */
+function getLastActivity(data) {
+    return data?.LastActivity ? new Date(data.LastActivity) : null;
+}
+
+/**
+ * Check if investor is verified.
+ * @param {Object} data - rankings_data object
+ * @returns {boolean}
+ */
+function isVerified(data) {
+    return data?.Verified === true;
+}
+
+/**
+ * Check if investor is blocked.
+ * @param {Object} data - rankings_data object
+ * @returns {boolean}
+ */
+function isBlocked(data) {
+    return data?.Blocked === true;
+}
+
+/**
+ * Check if investor is a Popular Investor.
+ * @param {Object} data - rankings_data object
+ * @returns {boolean}
+ */
+function isPopularInvestor(data) {
+    return data?.PopularInvestor === true;
+}
+
+/**
+ * Get country.
+ * @param {Object} data - rankings_data object
+ * @returns {string}
+ */
+function getCountry(data) {
+    return data?.Country || 'Unknown';
+}
+
+/**
+ * Get full name (if displayed).
+ * @param {Object} data - rankings_data object
+ * @returns {string|null}
+ */
+function getFullName(data) {
+    return data?.DisplayFullName ? data.FullName : null;
+}
+
+// =============================================================================
+// CALCULATED METRICS
+// =============================================================================
+
+/**
+ * Calculate a simple PI quality score (0-100).
+ * @param {Object} data - rankings_data object
+ * @returns {number}
+ */
+function calculateQualityScore(data) {
+    let score = 50;
+    
+    // Performance (+/- 20)
+    const gain = getTotalGain(data);
+    if (gain > 100) score += 20;
+    else if (gain > 50) score += 10;
+    else if (gain < 0) score -= 20;
+    else if (gain < 20) score -= 10;
+    
+    // Risk (+/- 15)
+    const risk = getRiskScore(data);
+    if (risk <= 3) score += 15;
+    else if (risk <= 5) score += 5;
+    else if (risk >= 8) score -= 15;
+    else if (risk >= 7) score -= 5;
+    
+    // Drawdown (+/- 10)
+    const drawdown = Math.abs(getPeakToValley(data));
+    if (drawdown < 15) score += 10;
+    else if (drawdown > 40) score -= 10;
+    
+    // Win ratio (+/- 10)
+    const winRatio = getWinRatio(data);
+    if (winRatio >= 70) score += 10;
+    else if (winRatio < 50) score -= 10;
+    
+    // Copiers (+/- 5)
+    const copierChange = getCopierChangePct(data);
+    if (copierChange > 10) score += 5;
+    else if (copierChange < -10) score -= 5;
+    
+    return Math.max(0, Math.min(100, score));
+}
+
+/**
+ * Summarize a PI's key metrics.
+ * @param {Object} row - pi_rankings row
+ * @returns {Object}
+ */
+function summarize(row) {
+    const data = extractRankingsData(row);
+    if (!data) return null;
+    
+    return {
+        piId: getPiId(row),
+        username: getUsername(row),
+        rank: row?.rank,
+        
+        // Performance
+        totalGain: getTotalGain(data),
+        weeklyGain: getWeeklyGain(data),
+        winRatio: getWinRatio(data),
+        profitableWeeksPct: getProfitableWeeksPct(data),
+        
+        // Risk
+        riskScore: getRiskScore(data),
+        riskTier: getRiskTier(getRiskScore(data)),
+        maxDrawdown: getPeakToValley(data),
+        
+        // AUM & Copiers
+        aum: getAUM(data),
+        aumTier: getAUMTierDesc(data),
+        copiers: getCopiers(data),
+        copierChange: getCopierChange(data),
+        
+        // Trading style
+        exposure: getExposure(data),
+        longPct: getLongPosPct(data),
+        avgPosSize: getAvgPosSize(data),
+        
+        // Quality
+        qualityScore: calculateQualityScore(data),
+        
+        // Status
+        isVerified: isVerified(data),
+        country: getCountry(data)
+    };
+}
+
+module.exports = {
+    // Data extraction
+    extractRankingsData,
+    getPiId,
+    getUsername,
+    
+    // Risk metrics
+    getRiskScore,
+    getMaxDailyRiskScore,
+    getMaxMonthlyRiskScore,
+    getDailyDrawdown,
+    getWeeklyDrawdown,
+    getPeakToValley,
+    getRiskTier,
+    
+    // Performance metrics
+    getTotalGain,
+    getDailyGain,
+    getWeeklyGain,
+    getWinRatio,
+    getProfitableWeeksPct,
+    getProfitableMonthsPct,
+    getCopiersGain,
+    
+    // AUM & Copiers
+    getAUM,
+    getAUMTier,
+    getAUMTierDesc,
+    getCopiers,
+    getBaselineCopiers,
+    getCopierChange,
+    getCopierChangePct,
+    
+    // Trading style
+    getExposure,
+    getLongPosPct,
+    getShortPosPct,
+    getAvgPosSize,
+    getTotalTrades,
+    getTotalInstruments,
+    getLeverageBreakdown,
+    getTradingStyle,
+    
+    // Top asset
+    getTopInstrumentId,
+    getTopInstrumentPct,
+    getTopAssetClassId,
+    getTags,
+    
+    // Activity & Status
+    getActiveWeeks,
+    getActiveWeeksPct,
+    getWeeksSinceRegistration,
+    getFirstActivity,
+    getLastActivity,
+    isVerified,
+    isBlocked,
+    isPopularInvestor,
+    getCountry,
+    getFullName,
+    
+    // Calculated
+    calculateQualityScore,
+    summarize
+};