feat(funds): implement fund ledger system and wallet management

VERSION

@@ -1 +1 @@
-2.0.0
+2.0.1

alembic/versions/a62763117ed4_add_fund_ledger_system.py

@@ -0,0 +1,92 @@
+"""add_fund_ledger_system
+
+Revision ID: a62763117ed4
+Revises: 762a64d64b9d
+Create Date: 2026-02-25 16:21:58.440948
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = 'a62763117ed4'
+down_revision: Union[str, None] = '762a64d64b9d'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('fund_ledger',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('trading_mode', sa.String(length=20), nullable=False),
+    sa.Column('transaction_type', sa.String(length=10), nullable=False),
+    sa.Column('category', sa.String(length=50), nullable=False),
+    sa.Column('amount', sa.Numeric(precision=15, scale=2), nullable=False),
+    sa.Column('balance_before', sa.Numeric(precision=15, scale=2), nullable=False),
+    sa.Column('balance_after', sa.Numeric(precision=15, scale=2), nullable=False),
+    sa.Column('description', sa.String(length=255), nullable=True),
+    sa.Column('reference_id', sa.String(length=100), nullable=True),
+    sa.Column('timestamp', sa.DateTime(), nullable=True),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index('idx_ledger_user_mode', 'fund_ledger', ['user_id', 'trading_mode'], unique=False)
+    op.create_index(op.f('ix_fund_ledger_category'), 'fund_ledger', ['category'], unique=False)
+    op.create_index(op.f('ix_fund_ledger_id'), 'fund_ledger', ['id'], unique=False)
+    op.create_index(op.f('ix_fund_ledger_reference_id'), 'fund_ledger', ['reference_id'], unique=False)
+    op.create_index(op.f('ix_fund_ledger_timestamp'), 'fund_ledger', ['timestamp'], unique=False)
+    op.create_index(op.f('ix_fund_ledger_trading_mode'), 'fund_ledger', ['trading_mode'], unique=False)
+    op.create_index(op.f('ix_fund_ledger_user_id'), 'fund_ledger', ['user_id'], unique=False)
+    op.drop_index('idx_trading_log_level_component', table_name='trading_system_logs')
+    op.drop_index('idx_trading_log_timestamp', table_name='trading_system_logs')
+    op.drop_index('ix_trading_system_logs_component', table_name='trading_system_logs')
+    op.drop_index('ix_trading_system_logs_id', table_name='trading_system_logs')
+    op.drop_index('ix_trading_system_logs_log_level', table_name='trading_system_logs')
+    op.drop_index('ix_trading_system_logs_timestamp', table_name='trading_system_logs')
+    op.drop_index('ix_trading_system_logs_trade_id', table_name='trading_system_logs')
+    op.drop_index('ix_trading_system_logs_user_id', table_name='trading_system_logs')
+    op.drop_table('trading_system_logs')
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('trading_system_logs',
+    sa.Column('id', sa.INTEGER(), autoincrement=True, nullable=False),
+    sa.Column('log_level', sa.VARCHAR(length=20), autoincrement=False, nullable=False),
+    sa.Column('component', sa.VARCHAR(length=50), autoincrement=False, nullable=False),
+    sa.Column('message', sa.TEXT(), autoincrement=False, nullable=False),
+    sa.Column('user_id', sa.INTEGER(), autoincrement=False, nullable=True),
+    sa.Column('trade_id', sa.VARCHAR(length=50), autoincrement=False, nullable=True),
+    sa.Column('symbol', sa.VARCHAR(length=20), autoincrement=False, nullable=True),
+    sa.Column('latency_ms', sa.INTEGER(), autoincrement=False, nullable=True),
+    sa.Column('function_name', sa.VARCHAR(length=100), autoincrement=False, nullable=True),
+    sa.Column('line_number', sa.INTEGER(), autoincrement=False, nullable=True),
+    sa.Column('stack_trace', sa.TEXT(), autoincrement=False, nullable=True),
+    sa.Column('additional_data', postgresql.JSON(astext_type=sa.Text()), autoincrement=False, nullable=True),
+    sa.Column('timestamp', postgresql.TIMESTAMP(), autoincrement=False, nullable=True),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], name='trading_system_logs_user_id_fkey', ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name='trading_system_logs_pkey')
+    )
+    op.create_index('ix_trading_system_logs_user_id', 'trading_system_logs', ['user_id'], unique=False)
+    op.create_index('ix_trading_system_logs_trade_id', 'trading_system_logs', ['trade_id'], unique=False)
+    op.create_index('ix_trading_system_logs_timestamp', 'trading_system_logs', ['timestamp'], unique=False)
+    op.create_index('ix_trading_system_logs_log_level', 'trading_system_logs', ['log_level'], unique=False)
+    op.create_index('ix_trading_system_logs_id', 'trading_system_logs', ['id'], unique=False)
+    op.create_index('ix_trading_system_logs_component', 'trading_system_logs', ['component'], unique=False)
+    op.create_index('idx_trading_log_timestamp', 'trading_system_logs', ['timestamp'], unique=False)
+    op.create_index('idx_trading_log_level_component', 'trading_system_logs', ['log_level', 'component'], unique=False)
+    op.drop_index(op.f('ix_fund_ledger_user_id'), table_name='fund_ledger')
+    op.drop_index(op.f('ix_fund_ledger_trading_mode'), table_name='fund_ledger')
+    op.drop_index(op.f('ix_fund_ledger_timestamp'), table_name='fund_ledger')
+    op.drop_index(op.f('ix_fund_ledger_reference_id'), table_name='fund_ledger')
+    op.drop_index(op.f('ix_fund_ledger_id'), table_name='fund_ledger')
+    op.drop_index(op.f('ix_fund_ledger_category'), table_name='fund_ledger')
+    op.drop_index('idx_ledger_user_mode', table_name='fund_ledger')
+    op.drop_table('fund_ledger')
+    # ### end Alembic commands ###

database/models.py

@@ -1485,6 +1485,42 @@ class TradingAuditTrail(Base):
     )
 
 
+class FundLedger(Base):
+    """
+    Transaction ledger for tracking all fund movements (Credits/Debits)
+    Behaves like a real bank/brokerage statement.
+    """
+    __tablename__ = "fund_ledger"
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=False)
+
+    # paper or live
+    trading_mode = Column(String(20), nullable=False, index=True)
+
+    # CREDIT (Money coming in) or DEBIT (Money going out)
+    transaction_type = Column(String(10), nullable=False)
+
+    # FUND_ADDED, TRADE_MARGIN_BLOCKED, TRADE_MARGIN_RELEASED, PNL_SETTLEMENT, CHARGES, BROKERAGE
+    category = Column(String(50), nullable=False, index=True)
+
+    amount = Column(Numeric(15, 2), nullable=False)
+    balance_before = Column(Numeric(15, 2), nullable=False)
+    balance_after = Column(Numeric(15, 2), nullable=False)
+
+    description = Column(String(255))
+    reference_id = Column(String(100), index=True) # trade_id or transaction_id
+
+    timestamp = Column(DateTime, default=get_ist_now_naive, index=True)
+
+    # Relationships
+    user = relationship("User")
+
+    __table_args__ = (
+        Index("idx_ledger_user_mode", "user_id", "trading_mode"),
+    )
+
+
 # =======================
 # PREMARKET CANDLE & GAP DETECTION SYSTEM
 # =======================

docs/CHANGELOG.md

@@ -1,6 +1,29 @@
-# 📝 Changelog
+# 📠Changelog
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
-- Ongoing improvements and bug fixes.
+## [2.0.1] - 2026-02-25
+### Added
+- **AI-Powered Development Agents:**
+  - Automated Issue Triager for bug analysis using Gemini.
+  - Automated PR Reviewer for code quality, complexity (radon), and risk checks.
+  - Automated Backtesting for strategy performance validation in pull requests.
+  - AI Documentation Agent for automated semantic changelogs.
+  - Trading Risk Guard for detecting dangerous code patterns (hardcoded secrets, unlocalized time).
+- **Fund Ledger System:**
+  - Database-backed fund ledger tracking all deposits and withdrawals.
+  - Integration with `CapitalManager` for accurate balance management across brokers.
+  - New UI components: `AddFundsModal`, `FundStatementTable`, and `FundsTab` in profile.
+- **AI Support & Telegram Integration:**
+  - `AISupportService` for context-aware support answering queries using project docs and trade history.
+  - Telegram bot for remote support and account status tracking.
+
+### Changed
+- Refactored `execution_handler.py` and `pnl_tracker.py` to utilize the new `FundManager` for balance synchronization.
+- Enhanced `AutoTradingPage` for better performance and list virtualization.
+- Updated `requirements.txt` with `google-generativeai` and `PyGithub`.
+
+### Fixed
+- Improved timezone handling for IST consistency across services.
+- Corrected paper trading P&L logic for accurate balance updates.
+- Refined stock selection direction logic for neutral market conditions.

router/trading_execution_router.py

@@ -35,6 +35,7 @@
 from services.trading_execution.multi_demat_capital_service import (
     multi_demat_capital_service,
 )
+from services.trading_execution.fund_manager import fund_manager
 
 logging.basicConfig(
     level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
@@ -1881,3 +1882,50 @@
     except Exception as e:
         logger.error(f"Error getting detailed performance: {e}")
         raise HTTPException(status_code=500, detail=str(e))
+
+
+# ==================== FUND MANAGEMENT ENDPOINTS ====================
+
+@router.get("/funds/balance")
+async def get_fund_balances(
+    trading_mode: str = Query("paper", description="paper or live"),
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Get available, used and total balance"""
+    try:
+        balances = fund_manager.get_balances(current_user.id, db, trading_mode)
+        return {"success": True, "balances": balances}
+    except Exception as e:
+        logger.error(f"Error fetching balances: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/funds/add-paper-funds")
+async def add_paper_funds(
+    amount: float = Query(..., gt=0, description="Amount to add"),
+    description: str = Query("Manual top-up", description="Transaction description"),
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Add virtual funds to paper trading account"""
+    try:
+        result = fund_manager.add_paper_funds(current_user.id, amount, db, description)
+        return result
+    except Exception as e:
+        logger.error(f"Error adding funds: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/funds/statement")
+async def get_fund_statement(
+    trading_mode: str = Query("paper", description="paper or live"),
+    limit: int = Query(50, description="Max entries to return"),
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Get transaction ledger/statement"""
+    try:
+        statement = fund_manager.get_statement(current_user.id, db, trading_mode, limit)
+        return {"success": True, "statement": statement}
+    except Exception as e:
+        logger.error(f"Error fetching statement: {e}")
+        raise HTTPException(status_code=500, detail=str(e))

services/paper_trading_account.py

@@ -116,18 +116,8 @@ async def sync_with_db(self, user_id: int, db: Session) -> Optional[PaperAccount
             db_account = db.query(PaperTradingAccount).filter(PaperTradingAccount.user_id == user_id).first()
 
             if not db_account:
-                # Create default in DB if not exists
-                db_account = PaperTradingAccount(
-                    user_id=user_id,
-                    initial_capital=100000.0,
-                    current_balance=100000.0,
-                    available_margin=100000.0,
-                    used_margin=0.0,
-                    total_pnl=0.0
-                )
-                db.add(db_account)
-                db.commit()
-                db.refresh(db_account)
+                logger.warning(f"No paper account found in DB for user {user_id}. Fund management required.")
+                return None
 
             # Update in-memory
             account = PaperAccount(
@@ -163,16 +153,7 @@ def execute_paper_trade_sync(self, user_id: int, trade_data: Dict[str, Any], db:
             db_acc = db.query(PaperTradingAccount).filter(PaperTradingAccount.user_id == user_id).first()
 
             if not db_acc:
-                db_acc = PaperTradingAccount(
-                    user_id=user_id,
-                    initial_capital=100000.0,
-                    current_balance=100000.0,
-                    available_margin=100000.0,
-                    used_margin=0.0,
-                    total_pnl=0.0
-                )
-                db.add(db_acc)
-                db.flush()
+                raise ValueError(f"No paper trading account found for user {user_id}. Please add funds first.")
 
             invested_amount = float(trade_data['invested_amount'])
             entry_charges = 20.0