b4cddf41ea
- Fork elmeg-demo codebase for multi-band support - Add data importer infrastructure with base class - Create band-specific importers: - phish.py: Phish.net API v5 - grateful_dead.py: Grateful Stats API - setlistfm.py: Dead & Company, Billy Strings (Setlist.fm) - Add spec-kit configuration for Gemini - Update README with supported bands and architecture
248 lines
5.4 KiB
Markdown
248 lines
5.4 KiB
Markdown
# Elmeg Bug Tracker Spec
|
|
|
|
**Domain:** bugs.elmeg.xyz
|
|
**Style:** Zendesk-inspired support portal
|
|
**Date:** 2023-12-23
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
A lightweight, self-hosted bug/feedback tracker with a clean, user-first interface. Users can submit issues, track status, and browse known issues. Admins can triage, respond, and resolve.
|
|
|
|
---
|
|
|
|
## User-Facing Features
|
|
|
|
### 1. Submit a Report
|
|
|
|
- **Type:** Bug, Feature Request, Question, Other
|
|
- **Title:** Short description (required)
|
|
- **Description:** Rich text with markdown support
|
|
- **Attachments:** Screenshot upload (optional)
|
|
- **Priority:** (auto or user-selectable) Low, Medium, High, Critical
|
|
- **Email:** For anonymous users (logged-in users auto-fill)
|
|
- **Environment:** Auto-capture: Browser, OS, page URL
|
|
|
|
### 2. My Tickets
|
|
|
|
- View submitted tickets
|
|
- Track status: Open → In Progress → Resolved → Closed
|
|
- Add comments/updates to existing tickets
|
|
- Receive email notifications on updates
|
|
|
|
### 3. Knowledge Base / Known Issues
|
|
|
|
- Browse open bugs (public visibility toggle per ticket)
|
|
- Search functionality
|
|
- "Me too" upvote button
|
|
- FAQ section
|
|
|
|
### 4. Anonymous vs Authenticated
|
|
|
|
- Logged-in Elmeg users: auto-linked, no email required
|
|
- Anonymous: requires email for updates
|
|
|
|
---
|
|
|
|
## Admin Features
|
|
|
|
### Dashboard
|
|
|
|
- Ticket queue (filterable by status, type, priority, date)
|
|
- Unassigned tickets highlight
|
|
- Metrics: open count, avg response time, resolution rate
|
|
|
|
### Ticket Management
|
|
|
|
- Assign to self or team member
|
|
- Internal notes (not visible to user)
|
|
- Public reply
|
|
- Change status, priority, type
|
|
- Merge duplicate tickets
|
|
- Mark as known issue (public)
|
|
|
|
### Canned Responses
|
|
|
|
- Pre-written templates for common issues
|
|
- Variable substitution: `{user_name}`, `{ticket_id}`
|
|
|
|
---
|
|
|
|
## Technical Architecture
|
|
|
|
### Stack
|
|
|
|
- **Frontend:** Next.js (standalone app, shares Elmeg styling)
|
|
- **Backend:** FastAPI (can share auth with main Elmeg backend)
|
|
- **Database:** PostgreSQL (new schema in same db or separate)
|
|
- **Storage:** S3/local for attachments
|
|
|
|
### Models
|
|
|
|
```
|
|
Ticket
|
|
├── id (uuid)
|
|
├── ticket_number (auto-increment display ID: ELM-001)
|
|
├── type (bug | feature | question | other)
|
|
├── status (open | in_progress | resolved | closed)
|
|
├── priority (low | medium | high | critical)
|
|
├── title
|
|
├── description
|
|
├── reporter_email
|
|
├── reporter_user_id (nullable, FK to elmeg user)
|
|
├── assigned_to (nullable, FK to admin user)
|
|
├── is_public (for known issues)
|
|
├── upvotes
|
|
├── environment (JSON: browser, os, url)
|
|
├── created_at
|
|
├── updated_at
|
|
├── resolved_at
|
|
|
|
TicketComment
|
|
├── id
|
|
├── ticket_id (FK)
|
|
├── author_id (FK)
|
|
├── author_email (for anonymous)
|
|
├── content
|
|
├── is_internal (admin-only visibility)
|
|
├── created_at
|
|
|
|
TicketAttachment
|
|
├── id
|
|
├── ticket_id (FK)
|
|
├── filename
|
|
├── url
|
|
├── created_at
|
|
|
|
CannedResponse
|
|
├── id
|
|
├── title
|
|
├── content
|
|
├── created_by
|
|
```
|
|
|
|
### API Endpoints
|
|
|
|
**Public:**
|
|
|
|
- `POST /tickets` - Create ticket
|
|
- `GET /tickets/{ticket_number}` - View ticket (if public or owned)
|
|
- `POST /tickets/{id}/comments` - Add comment
|
|
- `POST /tickets/{id}/upvote` - Upvote known issue
|
|
- `GET /known-issues` - List public tickets
|
|
|
|
**Authenticated (Elmeg user):**
|
|
|
|
- `GET /my-tickets` - User's tickets
|
|
|
|
**Admin:**
|
|
|
|
- `GET /admin/tickets` - All tickets (filtered)
|
|
- `PATCH /admin/tickets/{id}` - Update status, assign, etc.
|
|
- `POST /admin/tickets/{id}/internal-note` - Add internal note
|
|
- `GET /admin/canned-responses`
|
|
- `POST /admin/canned-responses`
|
|
|
|
---
|
|
|
|
## UI Pages
|
|
|
|
| Route | Purpose |
|
|
|-------|---------|
|
|
| `/` | Landing: "How can we help?" + Submit form |
|
|
| `/submit` | Full bug report form |
|
|
| `/my-tickets` | User's submitted tickets |
|
|
| `/ticket/[id]` | Ticket detail + comments |
|
|
| `/known-issues` | Public bug list with search |
|
|
| `/admin` | Admin dashboard |
|
|
| `/admin/ticket/[id]` | Admin ticket view |
|
|
|
|
---
|
|
|
|
## Email Notifications
|
|
|
|
| Event | Recipient |
|
|
|-------|-----------|
|
|
| Ticket created | User (confirmation) |
|
|
| Admin replies | User |
|
|
| Status changed | User |
|
|
| User comment | Assigned admin |
|
|
|
|
Uses existing AWS SES integration.
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
### Docker Compose (separate service)
|
|
|
|
```yaml
|
|
services:
|
|
bugs-frontend:
|
|
build: ./bugs-frontend
|
|
labels:
|
|
- "traefik.http.routers.bugs.rule=Host(`bugs.elmeg.xyz`)"
|
|
|
|
bugs-backend:
|
|
build: ./bugs-backend
|
|
environment:
|
|
- DATABASE_URL=postgresql://...
|
|
- ELMEG_API_URL=https://elmeg.xyz/api
|
|
```
|
|
|
|
### DNS
|
|
|
|
Add A record or CNAME for `bugs.elmeg.xyz` → production server
|
|
|
|
### Auth Integration
|
|
|
|
- Share JWT validation with main Elmeg backend
|
|
- Or standalone with optional Elmeg SSO
|
|
|
|
---
|
|
|
|
## MVP Scope (Phase 1)
|
|
|
|
- [ ] Submit ticket form
|
|
- [ ] My tickets list
|
|
- [ ] Ticket detail with comments
|
|
- [ ] Admin ticket queue
|
|
- [ ] Email on ticket creation
|
|
- [ ] Basic styling matching Elmeg
|
|
|
|
## Phase 2
|
|
|
|
- [ ] Known issues page
|
|
- [ ] Upvoting
|
|
- [ ] Canned responses
|
|
- [ ] Internal notes
|
|
- [ ] Attachment uploads
|
|
- [ ] Search
|
|
|
|
## Phase 3
|
|
|
|
- [ ] Metrics dashboard
|
|
- [ ] Merge tickets
|
|
- [ ] Tags/labels
|
|
- [ ] Webhook integrations (Discord, Slack)
|
|
|
|
---
|
|
|
|
## Estimated Effort
|
|
|
|
| Phase | Effort |
|
|
|-------|--------|
|
|
| MVP | 2-3 days |
|
|
| Phase 2 | 2 days |
|
|
| Phase 3 | 2 days |
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. Create `/srv/containers/elmeg-bugs` directory structure
|
|
2. Initialize Next.js + FastAPI project
|
|
3. Set up Traefik routing for `bugs.elmeg.xyz`
|
|
4. Implement MVP models + endpoints
|
|
5. Deploy
|