# Oikka Capital - User Manual Welcome to Oikka Capital! This manual provides a quick-start guide to logging in, managing installment payments, and tracking business investments. --- ## 🔑 Login Credentials The local database comes pre-seeded with the following default test accounts: * **Super Admin / Admin:** * **Email:** `test@example.com` * **Password:** `password` * **Founder:** * **Email:** `investor@example.com` (or other founder accounts in database) * **Password:** `password` * **Member:** * **Email:** (Find any member email in the Users Directory or database `users` table) * **Password:** `password` --- ## 🛡️ Roles & Privileges The system separates privileges using four core roles: 1. **Super Admin / Admin:** Full system privileges (Create/Edit members, manage roles and permissions, record installments, approve receipts, register businesses, launch investment opportunities). 2. **Founder:** Managed businesses operational visibility. Can register new businesses under their name, and log weekly collections (returns). 3. **Member:** Can view personal statistics, view active investments they have shares in, and submit installment payments. Fully isolated data access—members only see their own records. --- ## 💳 Payments Ledger Guide ### 1. Paying Installments (For Members) * Log in as a Member and navigate to the **Payments** tab. * Click **Pay Installment**. * Enter the amount, select the **Payment Method** (Bank, bKash, or Cash - defaults to Bank), and add an optional **Reference / Transaction ID**. * Submit the form. The installment will be submitted with a status of `pending` for admin review. > [!NOTE] > All payment submissions are protected against double submission. The submission button will automatically disable during processing. ### 2. Recording Installments (For Admins) * Log in as an Admin and navigate to the **Payments** tab. * Click **Record Installment**. * Select the member from the dropdown selection (the modal automatically fills their default profile amount). * Enter the amount, select the payment method and reference, choose the status (`pending` or `received`), and submit. ### 3. Requesting Deposit Withdrawals (For Members) * Log in as a Member and navigate to the **Payments** tab. * Click **Request Withdrawal**. * Enter the amount to withdraw, select the **Payout Method** (bKash, Bank Transfer, or Cash), and specify your payout account details/reference. > [!IMPORTANT] > **Available Balance Limit:** You can only withdraw up to your **Effective Available Balance** (uncommitted funds sitting idle in the pool). Funds already locked in active investments cannot be withdrawn directly. * Submit the form. The request will enter a `pending` review status, soft-reserving the requested funds so they cannot be double-spent or over-allocated. ### 4. Approving or Rejecting Requests (For Admins) * Navigate to the **Payments** list. Filter by status (`Pending`) or type (`Withdrawal`). * **To Approve:** Click **Approve** (or Mark Received). Review transaction details and confirm payout dispatch. * **To Reject:** Click **Reject**. The rejection immediately unreserves the soft-locked funds back to the member's effective available balance. --- ## 📈 Businesses & Investments Guide ### 1. Creating a Business (Admins/Founders) * Go to the **Businesses** tab and click **Create Business**. * Admins can assign the business to any user with the `'founder'` role. Founders are automatically assigned as the manager of their created businesses. ### 2. Adding Collection Returns (Admins/Managing Founders) * Open the business operational detail view. * Click **Add Collection**. Enter the collected return amount, date, description, and choose if the return should be distributed as payments or reinvested. * **Distribution Mode (default):** Distributes the return amount to each member's balance as a `collection_return` payment, proportional to their invested share. * **Reinvestment Mode:** Freezes the return directly as a new Investment in the same business, with shares proportional to existing investment amounts. * Reinvestment percentages are apportioned from the final contributions and total exactly **100.00%**. ### 3. Launching an Investment Opportunity (Admins only) * Open the business operational detail view and click **New Investment**. * Enter the total capital to raise. * The system automatically generates a preview table displaying each member's percentage share and contribution amount based on their available balances. * Default percentages total exactly **100.00%** when funds are available. Any rounding remainder is allocated in 0.01% increments; members with no effective available balance receive 0.00%. > [!IMPORTANT] > **Individual Balance Enforcement:** A member's share amount cannot exceed their individual available balance. If you assign a share that exceeds a member's available balance: > * The balance text in the member row will highlight in **red** with an `(Exceeded)` warning label. > * The submit button will be disabled. * Adjust individual percentage inputs to total exactly **100.00%** and respect every member's effective available balance. Totals above or below 100.00% cannot be submitted. * Contributions are adjusted to the nearest paisa so their total matches the investment capital exactly. For example, three equal shares of Tk 100 become Tk 33.34, Tk 33.33, and Tk 33.33. The preview includes this adjustment, and the server verifies the final amounts against member balances. * Click **Freeze Shares & Invest** to lock the contribution shares for this opportunity. * These rounding rules apply to new investments; existing financial records remain unchanged. ### 4. Historical Rounding Correction The initial Tk 3 reconciliation migration corrects the original investment's member contributions from Tk 30,003 to Tk 30,000 and releases Tk 3 across the affected member balances. Its follow-up replays the three related reinvestments using corrected running ownership and makes each percentage total exactly 100.00%. Recorded profits stay unchanged; the third reinvestment moves Tk 0.01 from member #4's share to member #7's share. The follow-up does not change wallet balances or the later Tk 10,000 investment. These migrations must be applied separately; creating them does not change existing balances. See the technical documentation for the breakdown and application command. --- ## 📧 Automated Monthly Payment Reminders * **Schedule**: Automatically runs on the **4th of every month**. * **Target**: Any active member who has **not** submitted an installment deposit or withdrawal request for the current calendar month by the 4th. * **Email Content**: A branded reminder email containing the member's name, current month/year, and a direct button link to log into their dashboard and complete their payment. * **Manual Execution (Admins)**: Admins can trigger the reminder command manually via CLI: ```bash php artisan payments:send-monthly-reminder --force ```