230 lines
5.6 KiB
Markdown
230 lines
5.6 KiB
Markdown
# Admin Interface - Quick Start Guide
|
|
|
|
## Getting Started
|
|
|
|
### 1. Start the Development Server
|
|
|
|
```bash
|
|
# Option 1: Run server with Tailwind watch (recommended)
|
|
bin/dev
|
|
|
|
# Option 2: Run server only
|
|
bin/rails server
|
|
```
|
|
|
|
### 2. Access the Admin Interface
|
|
|
|
Open your browser and navigate to:
|
|
```
|
|
http://localhost:3000/admin/login
|
|
```
|
|
|
|
### 3. Login with Default Credentials
|
|
|
|
```
|
|
Email: admin@example.com
|
|
Password: password123
|
|
```
|
|
|
|
⚠️ **Important**: Change this password immediately in production!
|
|
|
|
## Interface Overview
|
|
|
|
### Dashboard (/)
|
|
- **Real-time Statistics**: View gateway counts, API keys, and message metrics
|
|
- **Recent Messages**: Monitor the latest 10 SMS messages
|
|
- **Gateway Status**: Check active gateways and their heartbeat status
|
|
|
|
### API Keys (/admin/api_keys)
|
|
- **List Keys**: View all API keys with status and permissions
|
|
- **Create New**: Generate API keys with custom permissions (Send SMS, Receive SMS, Manage Gateways)
|
|
- **Revoke Keys**: Deactivate keys that are no longer needed
|
|
- **One-time Display**: API keys are shown only once after creation for security
|
|
|
|
### SMS Logs (/admin/logs)
|
|
- **View All Messages**: Paginated list (50 per page) of all SMS traffic
|
|
- **Advanced Filters**:
|
|
- Direction (Inbound/Outbound)
|
|
- Status (Pending/Sent/Delivered/Failed)
|
|
- Phone number search
|
|
- Gateway selection
|
|
- Date range
|
|
- **Error Details**: Click on failed messages to view error information
|
|
|
|
### Gateways (/admin/gateways)
|
|
- **List Devices**: View all registered gateway devices
|
|
- **Device Details**: Click on gateway name for detailed stats
|
|
- **Toggle Status**: Activate or deactivate gateways
|
|
- **Monitor Health**: Check connection status, heartbeat, and message counts
|
|
|
|
## Key Features
|
|
|
|
### Status Indicators
|
|
- 🟢 **Green Pulse**: Gateway is online and active
|
|
- 🔴 **Red Dot**: Gateway is offline
|
|
- 🟡 **Yellow**: Pending or warning status
|
|
- 🔵 **Blue**: Information or in-progress status
|
|
|
|
### Color-Coded Badges
|
|
- **Green**: Success, Active, Delivered, Online
|
|
- **Blue**: Information, Sent, Outbound
|
|
- **Red**: Error, Failed, Revoked, Offline
|
|
- **Yellow**: Warning, Pending
|
|
- **Purple**: Queued, Priority
|
|
- **Gray**: Inactive, Neutral
|
|
|
|
### Quick Actions
|
|
- **Copy API Key**: One-click copy to clipboard
|
|
- **Filter & Search**: Quick filtering on all list views
|
|
- **Toggle States**: One-click activate/deactivate
|
|
- **View Details**: Click on links for detailed information
|
|
|
|
## Common Tasks
|
|
|
|
### Creating an API Key
|
|
1. Navigate to **API Keys** → **Create New API Key**
|
|
2. Enter a descriptive name
|
|
3. Select permissions (checkboxes)
|
|
4. Optionally set an expiration date
|
|
5. Click **Create API Key**
|
|
6. **Copy the key immediately** (shown only once!)
|
|
7. Store securely
|
|
|
|
### Monitoring Messages
|
|
1. Navigate to **SMS Logs**
|
|
2. Use filters to narrow down results:
|
|
- Select direction and status
|
|
- Enter phone number to search
|
|
- Choose specific gateway
|
|
- Set date range
|
|
3. Click **Apply Filters**
|
|
4. Click on any row with errors to view details
|
|
|
|
### Managing Gateways
|
|
1. Navigate to **Gateways**
|
|
2. View online/offline status
|
|
3. Click gateway name for detailed stats
|
|
4. Use **Activate/Deactivate** buttons to control gateway
|
|
|
|
### Checking Statistics
|
|
1. Dashboard shows current metrics:
|
|
- Total vs. online gateways
|
|
- Active API keys
|
|
- Messages today (sent/received)
|
|
- Failed messages count
|
|
2. All stats update on page refresh
|
|
|
|
## Navigation
|
|
|
|
### Sidebar Menu
|
|
- **Dashboard**: Home page with overview
|
|
- **API Keys**: Manage client API keys
|
|
- **SMS Logs**: View and filter messages
|
|
- **Gateways**: Manage gateway devices
|
|
|
|
### User Menu (Bottom of Sidebar)
|
|
- Shows your name and email
|
|
- **Logout** button
|
|
|
|
## Tips & Tricks
|
|
|
|
### Keyboard Navigation
|
|
- All interactive elements are keyboard accessible
|
|
- Use Tab to navigate between fields
|
|
- Enter to submit forms
|
|
|
|
### Search & Filter
|
|
- Phone number search accepts partial numbers
|
|
- Date filters are inclusive (includes start and end dates)
|
|
- Clear filters to reset to default view
|
|
|
|
### Visual Cues
|
|
- Hover over rows to highlight
|
|
- Online gateways show animated pulse
|
|
- Active states have distinct colors
|
|
- Error messages expand on click
|
|
|
|
### Mobile Support
|
|
- Sidebar collapses on mobile
|
|
- Tables scroll horizontally
|
|
- Touch-friendly button sizes
|
|
- Responsive grid layouts
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
```bash
|
|
bin/rails test
|
|
```
|
|
|
|
### Code Quality
|
|
```bash
|
|
bin/rubocop
|
|
bin/brakeman
|
|
```
|
|
|
|
### Database Management
|
|
```bash
|
|
# Reset and seed
|
|
bin/rails db:reset
|
|
|
|
# Just seed
|
|
bin/rails db:seed
|
|
```
|
|
|
|
### Building Tailwind CSS
|
|
```bash
|
|
# One-time build
|
|
bin/rails tailwindcss:build
|
|
|
|
# Watch mode (auto-rebuild)
|
|
bin/rails tailwindcss:watch
|
|
|
|
# Or use foreman to run both
|
|
bin/dev
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Can't Login
|
|
- Verify you ran `bin/rails db:seed`
|
|
- Check that Admin user exists: `bin/rails console` → `Admin.count`
|
|
- Verify email/password are correct
|
|
|
|
### Styling Looks Broken
|
|
- Run `bin/rails tailwindcss:build`
|
|
- Clear browser cache
|
|
- Check `app/assets/builds/tailwind.css` exists
|
|
|
|
### API Key Not Working
|
|
- Verify key is active (not revoked)
|
|
- Check key hasn't expired
|
|
- Ensure permissions are set correctly
|
|
|
|
### No Data Showing
|
|
- Run `bin/rails db:seed` to create sample data
|
|
- Check that gateway devices are registered
|
|
- Verify messages exist in database
|
|
|
|
## Security Checklist
|
|
|
|
- [ ] Change default admin password
|
|
- [ ] Use HTTPS in production
|
|
- [ ] Set secure session cookies
|
|
- [ ] Enable rate limiting
|
|
- [ ] Monitor admin access logs
|
|
- [ ] Regularly audit API keys
|
|
- [ ] Revoke unused API keys
|
|
- [ ] Set expiration dates on keys
|
|
|
|
## Getting Help
|
|
|
|
- Read full documentation: `ADMIN_INTERFACE.md`
|
|
- Check project docs: `CLAUDE.md`
|
|
- View Rails logs: `log/development.log`
|
|
- Rails console: `bin/rails console`
|
|
|
|
---
|
|
|
|
**Happy administering! 🎉**
|