# Investment Module Documentation ## Overview This documentation describes the new fixed-package USD investment feature added to the celebrity fan platform. It covers how users interact with the system, what administrators should monitor, and the relevant developer implementation details. --- ## User Guide ### What users can do - Fund a wallet using crypto or bank deposit requests. - Browse available fixed-yield USD investment plans. - Invest in a plan once their wallet balance is sufficient. - View active investments, matured payouts, referral bonuses, and withdrawal requests from the investment dashboard. - Request withdrawals from wallet balance. - Share their referral code to earn bonus credits when referred users invest. ### Key user flows 1. Deposit funds - Go to `Investments` → `Fund wallet`. - Choose deposit method: `USDT`, `BTC`, or `Bank Transfer`. - Enter the amount and submit the deposit request. - The deposit is saved as a pending `WalletTransaction` and reviewed manually before wallet crediting. 2. Browse plans - Go to `Investments` → `Investment plans`. - Select an active plan to see the fixed amount, duration, profit percentage, and payout. 3. Start an investment - On the plan checkout page, confirm the selected investment plan. - If wallet balance is sufficient, submit to create the investment. - The plan amount is withdrawn from the wallet and a new `Investment` is created. - If you were referred with `?ref=CODE`, the referrer receives a 5% bonus credited to their wallet. 4. Claim mature payouts - When an investment reaches its maturity date, claim the payout from your investment dashboard. - The payout amount plus profit is credited to your wallet. - After claiming, you can request a withdrawal. 5. Withdraw funds - Go to `Investments` → `Request withdrawal`. - Enter an amount and select a provider. - The withdrawal is recorded as a `WithdrawalRequest`. - Funds are removed from the wallet immediately and the request is pending approval. ### Referral system - Each user has a `referral_code` attached to their account. - Share a link with `?ref=` to refer new users. - When the referred user invests, the referrer receives a 5% bonus of the investment amount. - Referral bonuses are stored as `ReferralBonus` records and credited to the referrer wallet. --- ## Admin Guide ### Accessing admin investment management - Staff users can visit the staff dashboard and follow the link to the Investment Management page. - The admin investment management view is protected by `@staff_member_required` and located at `investments/admin/`. ### What admins can monitor - Total invested capital, active principal, completed payouts, withdrawn capital, and wallet liquidity. - Active investment plans and their current status. - Recent investments and recent withdrawal requests. - Pending and completed withdrawal activity. ### Admin responsibilities - Review pending wallet deposit requests and credit user wallets after external payment confirmation. - Review withdrawal requests and approve or reject them through the admin site or a future workflow. - Manage `InvestmentPlan` records in the Django admin to create, edit, deactivate, or remove plans. - Monitor referral bonus activity from the admin dashboard and associated transaction history. ### Key admin pages and models - `core.admin.InvestmentPlanAdmin` - `core.admin.InvestmentAdmin` - `core.admin.UserWalletAdmin` - `core.admin.WalletTransactionAdmin` - `core.admin.WithdrawalRequestAdmin` - `core.admin.ReferralBonusAdmin` --- ## Developer Guide ### Core models - `core.models.UserWallet` - tracks a user's wallet balance and provides `deposit` and `withdraw` helpers. - `core.models.WalletTransaction` - records deposit and withdrawal transaction requests. - `core.models.InvestmentPlan` - defines fixed investment amounts, duration, and profit percentages. - `core.models.Investment` - records user investments, start/end dates, status, profit, payout, and maturity. - `core.models.WithdrawalRequest` - captures withdrawal requests, provider, status, and processing metadata. - `core.models.ReferralBonus` - stores referral bonus events tied to investments. ### Important views - `core.views.investment_plans` - renders available active plans. - `core.views.investment_dashboard` - renders user wallet, investments, payouts, and referral details. - `core.views.checkout_investment` - verifies wallet balance, creates investments, withdraws wallet funds, and credits referral bonuses. - `core.views.wallet_deposit` - creates deposit requests via `WalletTransaction` - `core.views.withdrawal_request` - validates wallet balance and creates `WithdrawalRequest` - `core.views.claim_investment_payout` - deposits matured investment payout into the user's wallet and marks the investment completed. - `core.views.admin_investment_management` - staff-only dashboard with summary metrics and recent activity. ### URL configuration - `investments/` → `investment_dashboard` - `investments/plans/` → `investment_plans` - `investments/checkout//` → `checkout_investment` - `investments/deposit/` → `wallet_deposit` - `investments/withdraw/` → `withdrawal_request` - `investments/admin/` → `admin_investment_management` ### Templates - `templates/home.html` - investment section added to the platform home page - `core/templates/core/investment_plans.html` - `core/templates/core/investment_checkout.html` - `core/templates/core/investment_dashboard.html` - `core/templates/core/wallet_deposit.html` - `core/templates/core/withdrawal_request.html` - `core/templates/core/admin_investment_management.html` ### Migration notes - The investment module was introduced via `core/migrations/0007_investmentplan_investment_referralbonus_userwallet_and_more.py`. - Seed data for default plans was added in `core/migrations/0008_add_default_investment_plans.py`. - Existing user referral support was patched in `users/migrations/0003_customuser_referral_code_customuser_referred_by.py`. ### Implementation details and constraints - Wallet balances are stored in `balance` to avoid floating-point rounding issues. - Investment plan pricing and payouts are in USD and stored in cents. - Referral bonuses are calculated as 5% of the invested amount and are credited immediately to the referrer wallet when a referred user invests. - A user must have enough wallet balance before `checkout_investment` allows investment creation. - Deposits are currently recorded as pending `WalletTransaction` entries; an external review or payment confirmation process is required to update wallet balances. - Withdrawals are immediately removed from the wallet and stored as pending for follow-up. ### Recommended developer improvements - Add automated payment provider integration for `WalletTransaction` deposit completion. - Add an approval workflow for `WithdrawalRequest` processing. - Add asynchronous scheduled task to automatically complete matured investments and notify users. - Add protections for duplicate referral bonus credits and referral abuse. - Add explicit `created_by` or audit trail fields for admin operations if required. --- ## Notes - The investment module currently assumes USD-backed fixed plans and manual deposit/withdrawal review. - This documentation should be updated as payment provider integration and workflow automation are added.