111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
# Glossary Feature Specification
|
|
|
|
## Overview
|
|
|
|
A wiki-style glossary system for defining and explaining fandom-specific terms, slang, and concepts. Users can suggest entries, and moderators/admins approve them before publication.
|
|
|
|
## Use Cases
|
|
|
|
- **Jam Band Terms**: "Bustout", "Tease", "Segue", "Type II Jam"
|
|
- **Venue Nicknames**: "The Gorge", "Red Rocks"
|
|
- **Song Nicknames**: Already handled by `PerformanceNickname`, but glossary can define broader terms
|
|
- **Cultural References**: "Couch Tour", "Lot Scene", "Heady"
|
|
|
|
## Data Model
|
|
|
|
### GlossaryEntry
|
|
|
|
```python
|
|
class GlossaryEntry(SQLModel, table=True):
|
|
id: Optional[int] = Field(default=None, primary_key=True)
|
|
term: str = Field(unique=True, index=True)
|
|
definition: str = Field(description="Main definition text")
|
|
example: Optional[str] = Field(default=None, description="Usage example")
|
|
category: str = Field(default="general", index=True) # general, venue, song, culture
|
|
status: str = Field(default="pending", index=True) # pending, approved, rejected
|
|
suggested_by: int = Field(foreign_key="user.id")
|
|
created_at: datetime = Field(default_factory=datetime.utcnow)
|
|
updated_at: datetime = Field(default_factory=datetime.utcnow)
|
|
|
|
user: "User" = Relationship()
|
|
```
|
|
|
|
### GlossaryEdit (Revision History)
|
|
|
|
```python
|
|
class GlossaryEdit(SQLModel, table=True):
|
|
id: Optional[int] = Field(default=None, primary_key=True)
|
|
entry_id: int = Field(foreign_key="glossaryentry.id")
|
|
user_id: int = Field(foreign_key="user.id")
|
|
field_changed: str # definition, example, category
|
|
old_value: str
|
|
new_value: str
|
|
status: str = Field(default="pending") # pending, approved, rejected
|
|
created_at: datetime = Field(default_factory=datetime.utcnow)
|
|
|
|
entry: "GlossaryEntry" = Relationship()
|
|
user: "User" = Relationship()
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Public
|
|
|
|
- `GET /glossary/` - List all approved entries (with search/filter)
|
|
- `GET /glossary/{term}` - Get a specific entry by term
|
|
|
|
### Authenticated
|
|
|
|
- `POST /glossary/` - Suggest a new entry
|
|
- `POST /glossary/{id}/edit` - Suggest an edit to an existing entry
|
|
|
|
### Moderator/Admin
|
|
|
|
- `GET /moderation/queue/glossary` - List pending entries
|
|
- `PUT /moderation/glossary/{id}/{action}` - Approve/Reject entry
|
|
- `GET /moderation/queue/glossary-edits` - List pending edits
|
|
- `PUT /moderation/glossary-edits/{id}/{action}` - Approve/Reject edit
|
|
|
|
## Frontend Components
|
|
|
|
### Public
|
|
|
|
- `/glossary` - Glossary index page with search
|
|
- `/glossary/[term]` - Individual term page
|
|
|
|
### Authenticated
|
|
|
|
- "Suggest Term" button on glossary index
|
|
- "Suggest Edit" button on term pages
|
|
|
|
### Admin
|
|
|
|
- `/admin/glossary` - Queue for pending entries and edits
|
|
|
|
## Workflow
|
|
|
|
### New Entry
|
|
|
|
1. User submits a new term via form
|
|
2. Entry created with `status=pending`
|
|
3. Moderator reviews in `/admin/glossary`
|
|
4. On approval, `status=approved` and entry is public
|
|
|
|
### Edit Existing Entry
|
|
|
|
1. User clicks "Suggest Edit" on a term page
|
|
2. `GlossaryEdit` record created with `status=pending`
|
|
3. Moderator reviews edit
|
|
4. On approval, the `GlossaryEntry` is updated and `GlossaryEdit.status=approved`
|
|
|
|
## Integration Points
|
|
|
|
- **Search**: Include glossary terms in global search
|
|
- **Inline Tooltips**: Hovering over a glossary term in comments/reviews shows a tooltip with the definition
|
|
- **Auto-linking**: Detect glossary terms in user-generated content and auto-link them
|
|
|
|
## Future Enhancements
|
|
|
|
- **Voting**: Community voting on definitions
|
|
- **Aliases**: Multiple terms pointing to the same entry (e.g., "The Gorge" → "Gorge Amphitheatre")
|
|
- **Cross-references**: Link related terms
|