mirror of
https://github.com/acedanger/docs.git
synced 2025-12-05 22:50:12 -08:00
feat: Add CI/CD setup guide with Gitea Actions for trading analysis application
feat: Implement multi-user support with separate brokerage accounts and user authentication feat: Configure SSO authentication setup using Google OAuth 2.0 for secure access refactor: Update index page to reflect new Trading Analysis Dashboard features and descriptions docs: Enhance quickstart guide for deploying Trading Analysis Dashboard with detailed steps chore: Add runner configuration for Gitea Actions with logging and container settings
This commit is contained in:
Peter Wood
262
guides/setup/multi-user.mdx
Normal file
262
guides/setup/multi-user.mdx
Normal file
@@ -0,0 +1,262 @@
|
||||
---
|
||||
title: 'Multi-User Support'
|
||||
description: 'Configure multi-user support with separate brokerage accounts'
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The application supports multiple users, each with their own brokerage account numbers and transaction data. Users authenticate via Google OAuth and can set up their brokerage account number in their profile.
|
||||
|
||||
## Database Schema Changes
|
||||
|
||||
### New Tables
|
||||
|
||||
#### `trading_analysis.users`
|
||||
Stores user information from OAuth:
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `id` | Primary Key | User identifier |
|
||||
| `email` | Unique | User email address |
|
||||
| `name` | String | User's full name |
|
||||
| `google_sub` | String | Google OAuth subject ID |
|
||||
| `picture_url` | String | Profile picture URL |
|
||||
| `brokerage_account_number` | String | User's primary account |
|
||||
| `is_active` | Boolean | Account active status |
|
||||
| `created_at` | Timestamp | Creation date |
|
||||
| `updated_at` | Timestamp | Last update date |
|
||||
|
||||
#### `trading_analysis.brokerage_accounts`
|
||||
Cross-reference table for account numbers:
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `id` | Primary Key | Account identifier |
|
||||
| `account_number` | Unique | Brokerage account number |
|
||||
| `account_display_name` | String | Optional friendly name |
|
||||
| `user_id` | Foreign Key | Links to users table |
|
||||
| `is_primary` | Boolean | Primary account flag |
|
||||
| `created_at` | Timestamp | Creation date |
|
||||
| `updated_at` | Timestamp | Last update date |
|
||||
|
||||
### Updated Tables
|
||||
|
||||
All existing tables have been updated with a `brokerage_account_id` foreign key:
|
||||
- `raw_transactions`
|
||||
- `matched_trades`
|
||||
- `dividend_transactions`
|
||||
- `monthly_trading_summary`
|
||||
- `monthly_dividend_summary`
|
||||
- `monthly_combined_summary`
|
||||
- `processing_log`
|
||||
|
||||
## Migration Process
|
||||
|
||||
To migrate an existing database to support multiple users:
|
||||
|
||||
### Step 1: Run the Migration Script
|
||||
|
||||
```bash
|
||||
python migrate_to_multiuser.py
|
||||
```
|
||||
|
||||
### Step 2: Set Environment Variables (optional)
|
||||
|
||||
```bash
|
||||
export DEFAULT_MIGRATION_EMAIL="your-admin@example.com"
|
||||
export DEFAULT_MIGRATION_NAME="Admin User"
|
||||
export DEFAULT_BROKERAGE_ACCOUNT="YOUR_ACCOUNT_NUMBER"
|
||||
```
|
||||
|
||||
<Info>
|
||||
The migration script will create default values if these environment variables are not set.
|
||||
</Info>
|
||||
|
||||
### What the Migration Does
|
||||
|
||||
<Steps>
|
||||
<Step title="Create new tables">
|
||||
Creates `users` and `brokerage_accounts` tables
|
||||
</Step>
|
||||
<Step title="Add foreign keys">
|
||||
Adds `brokerage_account_id` columns to existing tables
|
||||
</Step>
|
||||
<Step title="Create default user">
|
||||
Creates a default user and account for existing data
|
||||
</Step>
|
||||
<Step title="Update transactions">
|
||||
Updates all existing transactions to reference the default account
|
||||
</Step>
|
||||
<Step title="Recreate views">
|
||||
Recreates database views to work with the new schema
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Application Changes
|
||||
|
||||
### User Profile Management
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Profile Page" icon="user">
|
||||
Users can now set their brokerage account number in their profile
|
||||
</Card>
|
||||
<Card title="Account Validation" icon="check">
|
||||
CSV uploads require a valid brokerage account number
|
||||
</Card>
|
||||
<Card title="Multiple Accounts" icon="building-columns">
|
||||
Users can have multiple brokerage accounts (future feature)
|
||||
</Card>
|
||||
<Card title="Data Isolation" icon="lock">
|
||||
Users only see their own transaction data
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Upload Process
|
||||
|
||||
1. **User Validation**: Checks that user has a brokerage account before allowing uploads
|
||||
2. **Account Association**: All uploaded transactions are associated with the user's account
|
||||
3. **Processing**: Modified `trading_analysis.py` to accept `--account-id` parameter
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
<Steps>
|
||||
<Step title="Login">
|
||||
User logs in via Google OAuth
|
||||
</Step>
|
||||
<Step title="User Creation">
|
||||
User record is created/updated in the database
|
||||
</Step>
|
||||
<Step title="Set Account">
|
||||
User sets their brokerage account number in profile
|
||||
</Step>
|
||||
<Step title="Link Account">
|
||||
Brokerage account record is created and linked to user
|
||||
</Step>
|
||||
<Step title="Upload Data">
|
||||
CSV uploads are associated with the user's account
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Database Queries
|
||||
|
||||
### User-Specific Data
|
||||
|
||||
All queries now need to filter by `brokerage_account_id`:
|
||||
|
||||
```sql
|
||||
-- Get user's transactions
|
||||
SELECT * FROM trading_analysis.raw_transactions rt
|
||||
JOIN trading_analysis.brokerage_accounts ba ON rt.brokerage_account_id = ba.id
|
||||
WHERE ba.user_id = ?;
|
||||
|
||||
-- Get user's trading performance
|
||||
SELECT * FROM trading_analysis.v_trading_performance
|
||||
WHERE user_email = 'user@example.com';
|
||||
```
|
||||
|
||||
### Updated Views
|
||||
|
||||
Views now include user context:
|
||||
|
||||
- `v_current_positions` - Shows account and user information
|
||||
- `v_trading_performance` - Includes user email and account number
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Migration Configuration
|
||||
DEFAULT_MIGRATION_EMAIL=your-admin@example.com
|
||||
DEFAULT_MIGRATION_NAME=Admin User
|
||||
DEFAULT_BROKERAGE_ACCOUNT=YOUR_ACCOUNT_NUMBER
|
||||
|
||||
# OAuth Configuration (existing)
|
||||
GOOGLE_CLIENT_ID=your-client-id
|
||||
GOOGLE_CLIENT_SECRET=your-client-secret
|
||||
AUTHORIZED_USERS=user1@example.com,user2@example.com
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
<Warning>
|
||||
User data isolation is critical for multi-user environments. Always verify queries filter by the correct account ID.
|
||||
</Warning>
|
||||
|
||||
1. **User Isolation**: Users can only see their own transaction data
|
||||
2. **Account Validation**: Brokerage account numbers are validated before processing
|
||||
3. **OAuth Integration**: User authentication is handled by Google OAuth
|
||||
4. **Data Protection**: User data is isolated by account ID in all database operations
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Multiple Accounts" icon="layer-group">
|
||||
Support for users with multiple brokerage accounts
|
||||
</Card>
|
||||
<Card title="Account Sharing" icon="share-nodes">
|
||||
Allow users to share specific accounts with other users
|
||||
</Card>
|
||||
<Card title="Admin Interface" icon="user-shield">
|
||||
Administrative interface for managing users and accounts
|
||||
</Card>
|
||||
<Card title="Data Export" icon="download">
|
||||
User-specific data export functionality
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Migration Fails">
|
||||
- Ensure database connection is working
|
||||
- Verify you have proper permissions
|
||||
- Check for existing foreign key constraints
|
||||
- Review migration logs for specific errors
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="User Profile Issues">
|
||||
- Check that OAuth is configured correctly
|
||||
- Verify user email is in AUTHORIZED_USERS
|
||||
- Check application logs for authentication errors
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Upload Failures">
|
||||
- Verify user has set brokerage account number in profile
|
||||
- Check CSV format matches expected schema
|
||||
- Review processing logs in `trading_analysis.log`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Data Not Showing">
|
||||
- Ensure queries are filtering by correct account ID
|
||||
- Verify user-account association is correct
|
||||
- Check database views are updated
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Database Verification
|
||||
|
||||
```sql
|
||||
-- Check user-account associations
|
||||
SELECT u.email, u.brokerage_account_number, ba.account_number, ba.is_primary
|
||||
FROM trading_analysis.users u
|
||||
LEFT JOIN trading_analysis.brokerage_accounts ba ON u.id = ba.user_id;
|
||||
|
||||
-- Check transaction associations
|
||||
SELECT COUNT(*) as transaction_count, ba.account_number, u.email
|
||||
FROM trading_analysis.raw_transactions rt
|
||||
JOIN trading_analysis.brokerage_accounts ba ON rt.brokerage_account_id = ba.id
|
||||
JOIN trading_analysis.users u ON ba.user_id = u.id
|
||||
GROUP BY ba.account_number, u.email;
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Portfolio Management" icon="chart-line" href="/features/portfolio-management">
|
||||
Set up portfolio tracking for your account
|
||||
</Card>
|
||||
<Card title="CSV Upload" icon="file-csv" href="/features/csv-upload">
|
||||
Learn how to upload transaction data
|
||||
</Card>
|
||||
</CardGroup>
|
||||
Reference in New Issue
Block a user