add dev docs

docs/EXPENSE_APPROVAL.md

@@ -0,0 +1,167 @@
+# Expense Approval Workflow
+
+## Overview
+
+The Castle extension now requires admin approval for all user-submitted expenses. This prevents invalid or incorrect expenses from affecting balances until they are verified by the Castle admin.
+
+## How It Works
+
+### 1. User Submits Expense
+- User fills out the expense form with description, amount, category, etc.
+- Expense is created with `flag='!'` (PENDING status)
+- Entry is saved to the database but **does not affect balances**
+
+### 2. Admin Reviews Pending Expenses
+- Admin sees "Pending Expense Approvals" card on the main page
+- Card shows all pending expenses with:
+  - Description and amount
+  - User who submitted it
+  - Date submitted
+  - Fiat amount (if applicable)
+  - Reference number
+
+### 3. Admin Takes Action
+
+#### Option A: Approve
+- Admin clicks "Approve" button
+- Entry flag changes from `!` to `*` (CLEARED)
+- Entry **now affects balances** (user's balance updates)
+- User sees the expense in their transaction history
+- Entry appears with green checkmark icon
+
+#### Option B: Reject
+- Admin clicks "Reject" button
+- Entry flag changes from `!` to `x` (VOID)
+- Entry **never affects balances**
+- Entry appears with grey cancel icon (voided)
+
+## Balance Calculation
+
+Only entries with `flag='*'` (CLEARED) are included in balance calculations:
+
+```sql
+-- Balance query excludes pending/flagged/voided entries
+SELECT SUM(debit), SUM(credit)
+FROM entry_lines el
+JOIN journal_entries je ON el.journal_entry_id = je.id
+WHERE el.account_id = :account_id
+AND je.flag = '*'  -- Only cleared entries
+```
+
+## Transaction Flags
+
+| Flag | Symbol | Status | Affects Balance | Description |
+|------|--------|--------|----------------|-------------|
+| `*` | ✅ | CLEARED | Yes | Confirmed and reconciled |
+| `!` | ⏱️ | PENDING | No | Awaiting approval |
+| `#` | 🚩 | FLAGGED | No | Needs review |
+| `x` | ❌ | VOID | No | Cancelled/rejected |
+
+## API Endpoints
+
+### Get Pending Entries (Admin Only)
+```
+GET /castle/api/v1/entries/pending
+Authorization: Admin Key
+
+Returns: list[JournalEntry]
+```
+
+### Approve Expense (Admin Only)
+```
+POST /castle/api/v1/entries/{entry_id}/approve
+Authorization: Admin Key
+
+Returns: JournalEntry (with flag='*')
+```
+
+### Reject Expense (Admin Only)
+```
+POST /castle/api/v1/entries/{entry_id}/reject
+Authorization: Admin Key
+
+Returns: JournalEntry (with flag='x')
+```
+
+## Implementation Details
+
+### Files Modified
+
+1. **views_api.py**
+   - Line 284: Set expenses to `JournalEntryFlag.PENDING` on creation
+   - Lines 181-197: Added `/api/v1/entries/pending` endpoint
+   - Lines 972-1011: Added approve endpoint
+   - Lines 1013-1053: Added reject endpoint
+
+2. **crud.py**
+   - Lines 315-329: Updated `get_account_balance()` to filter by flag
+   - Lines 367-376: Updated fiat balance calculation to filter by flag
+   - Lines 238-269: Fixed `get_all_journal_entries()` to parse flag/meta
+
+3. **index.html**
+   - Lines 157-209: Added "Pending Expense Approvals" card
+
+4. **index.js**
+   - Line 68: Added `pendingExpenses` data property
+   - Lines 497-511: Added `loadPendingExpenses()` method
+   - Lines 545-563: Added `approveExpense()` method
+   - Lines 564-580: Added `rejectExpense()` method
+   - Line 731: Load pending expenses on page load for admins
+
+## User Experience
+
+### For Regular Users
+1. Submit expense via "Add Expense" button
+2. See expense with orange pending icon (⏱️) in transaction list
+3. Balance does NOT change yet
+4. Wait for admin approval
+
+### For Admin (Super User)
+1. See "Pending Expense Approvals" card at top of page
+2. Review expense details
+3. Click "Approve" → User's balance updates
+4. Click "Reject" → Expense is voided, no balance change
+
+## Security
+
+- All approval endpoints require admin key
+- Super user check prevents regular users from approving their own expenses
+- Voided entries are never included in balance calculations
+- Full audit trail in `meta` field tracks who created and reviewed each entry
+
+## Testing
+
+1. **Submit test expense as regular user**
+   ```
+   POST /castle/api/v1/entries/expense
+   {
+     "description": "Test groceries",
+     "amount": 50.00,
+     "currency": "EUR",
+     "expense_account": "utilities",
+     "is_equity": false
+   }
+   ```
+
+2. **Verify it's pending**
+   - Check user balance → should NOT include this expense
+   - Check transaction list → should show orange pending icon
+
+3. **Login as admin and approve**
+   - See expense in "Pending Expense Approvals"
+   - Click "Approve"
+   - Verify user balance updates
+
+4. **Submit another expense and reject it**
+   - Submit expense
+   - Admin clicks "Reject"
+   - Verify balance never changed
+   - Entry shows grey cancel icon
+
+## Future Enhancements
+
+- [ ] Email notifications when expense is approved/rejected
+- [ ] Bulk approve/reject multiple expenses
+- [ ] Admin notes when rejecting (reason for rejection)
+- [ ] Expense revision system (user can edit and resubmit rejected expenses)
+- [ ] Approval workflow with multiple approvers