Split bonus and real energy accounts

[konard]

Bonus account should have expiring energy. For example we can set it to expire in 2 years.

Also this will limit an amount of bonus energy for referral program.

And now we can only add new bonus energy if yesterday user had spending.

If no spending (bonus or real energy) yesterday - now new bonus energy will be granted.

That should encourage to use our API and apps more.

Also we should notify users when their balance is increased.

[konard]

🤖 AI Analysis and Design Proposal

I've analyzed the current energy/balance system across the api-gateway and telegram-bot repositories and created a comprehensive design document for implementing the bonus and real energy account split.

Key Findings from Current System:

Current Token Structure:

• Single tokens_gpt field for all energy
• Daily cron job (midnight MSK) grants bonuses to ALL users (no activity check)
• Base: 10,000 + 500 per referral child
• Cap: No bonus if balance >= 30,000
• No expiration mechanism

Proposed Solution:

1. Split Energy Accounts

{
  tokens_gpt: 10000,        // Real energy (purchased, permanent)
  bonus_tokens: 5000,       // Bonus energy (with expiration)
  bonus_history: [          // Track each bonus grant
    {
      amount: 5000,
      granted_date: "2025-10-30T00:00:00Z",
      expires_date: "2027-10-30T00:00:00Z",  // 2 years!
      remaining: 5000,
      source: "daily_award" | "referral_activation"
    }
  ]
}

2. Daily Activity Requirement

NEW: Only grant daily bonus if user had ANY spending yesterday

Track with new fields:

• last_spending_date: Last day user spent energy
• total_spent_yesterday: Amount spent yesterday

3. Spending Priority

Use bonus energy FIRST (oldest grants first via FIFO), then real energy

4. Notifications

• Daily bonus granted → notify user
• Referral activated → notify user
• Bonus expiring soon (30 days) → warn user
• Balance increased → notify user

5. Expiration

Auto-cleanup expired bonuses during daily cron (after 2 years)

Implementation Phases:

Phase 1: Database migration in api-gateway
Phase 2: Update spending logic (FIFO bonus deduction)
Phase 3: Update daily award cron (add activity check)
Phase 4: Add notification system
Phase 5: Update telegram-bot UI
Phase 6: Testing

Repositories to Modify:

api-gateway:

• src/repositories/TokensRepository.js
• src/services/TokensService.js
• src/services/CompletionsService.js
• src/services/ReferralService.js
• Add: src/services/NotificationService.js

telegram-bot:

• bot/middlewares/MiddlewareAward.py
• js/src/bot/middlewares/MiddlewareAward.js
• Balance display commands
• Localization files

Full Design Document:

I've created a detailed design document with:

• Complete data structures
• Migration strategy
• API changes
• Implementation timeline (~20-25 hours)
• Success criteria

Would you like me to proceed with implementation? I can:

1. Start with Phase 1 (database migration) in api-gateway
2. Create separate PRs for each repository
3. Include comprehensive tests

Let me know if you'd like any adjustments to this design!