completed SMS gateway project
This commit is contained in:
Min Zeya Phyo
229
ADMIN_QUICKSTART.md
Normal file
229
ADMIN_QUICKSTART.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 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! 🎉**
|
||||
Reference in New Issue
Block a user