Add quick start guide for new features
This commit is contained in:
340
QUICKSTART.md
Normal file
340
QUICKSTART.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# BREEDR Quick Start Guide
|
||||
## Litter Management & Pedigree Visualization
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Pull the Feature Branch
|
||||
```bash
|
||||
git checkout feature/litter-management-and-pedigree
|
||||
```
|
||||
|
||||
### 2. Run Database Migration
|
||||
```bash
|
||||
node server/db/migrate_litter_id.js
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
Running litter_id migration...
|
||||
✓ Added litter_id column to dogs table
|
||||
✓ Created index on litter_id
|
||||
Migration completed successfully!
|
||||
```
|
||||
|
||||
### 3. Install Dependencies
|
||||
```bash
|
||||
cd client
|
||||
npm install
|
||||
cd ..
|
||||
```
|
||||
|
||||
### 4. Start the Application
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The server will start on `http://localhost:3000` and the client on `http://localhost:5173`
|
||||
|
||||
---
|
||||
|
||||
## Feature 1: Litter Management
|
||||
|
||||
### Creating Your First Litter
|
||||
|
||||
1. **Navigate to Litters**
|
||||
- Click "Litters" in the navigation menu
|
||||
- Click "Add New Litter" button
|
||||
|
||||
2. **Fill in Litter Details**
|
||||
- **Sire (Father)**: Select from dropdown of male dogs
|
||||
- **Dam (Mother)**: Select from dropdown of female dogs
|
||||
- **Breeding Date**: Date of breeding (required)
|
||||
- **Whelping Date**: Expected/actual birth date (optional)
|
||||
- **Expected Puppy Count**: Estimated number of puppies
|
||||
- **Notes**: Any additional breeding information
|
||||
|
||||
3. **Save the Litter**
|
||||
- Click "Create Litter"
|
||||
- Litter appears in the list with format: "Sire x Dam - Date"
|
||||
|
||||
### Adding Puppies to a Litter
|
||||
|
||||
#### Method 1: Link to Existing Litter (Recommended)
|
||||
|
||||
1. **Click "Add New Dog"**
|
||||
2. **Enter Puppy Details**
|
||||
- Name (required)
|
||||
- Breed (required)
|
||||
- Sex (required)
|
||||
- Birth Date
|
||||
- Color
|
||||
- Microchip
|
||||
|
||||
3. **Select Parent Method**
|
||||
- Choose "Link to Litter" radio button
|
||||
- Select the litter from dropdown
|
||||
- Parents are automatically filled!
|
||||
|
||||
4. **Save**
|
||||
- Click "Add Dog"
|
||||
- Puppy is now linked to the litter
|
||||
- Parent relationships are automatically created
|
||||
|
||||
#### Method 2: Manual Parent Selection
|
||||
|
||||
1. **Click "Add New Dog"**
|
||||
2. **Enter Puppy Details**
|
||||
3. **Select Parent Method**
|
||||
- Choose "Manual Parent Selection" radio button
|
||||
- Select Sire from male dogs dropdown
|
||||
- Select Dam from female dogs dropdown
|
||||
|
||||
4. **Save**
|
||||
- Puppy is created with selected parents
|
||||
- No litter association
|
||||
|
||||
### Viewing Litter Details
|
||||
|
||||
1. **Click on a Litter** in the list
|
||||
2. **See Litter Information:**
|
||||
- Sire and Dam details
|
||||
- Breeding and whelping dates
|
||||
- List of all puppies in the litter
|
||||
- Actual puppy count vs expected
|
||||
|
||||
### Editing a Litter
|
||||
|
||||
1. Click "Edit" on the litter
|
||||
2. Update breeding/whelping dates
|
||||
3. Modify notes
|
||||
4. **Note:** Cannot change sire/dam after creation
|
||||
|
||||
---
|
||||
|
||||
## Feature 2: Interactive Pedigree Tree
|
||||
|
||||
### Viewing a Pedigree
|
||||
|
||||
1. **From Dog List:**
|
||||
- Click on any dog
|
||||
- Click "View Pedigree" button
|
||||
|
||||
2. **Pedigree Opens in Modal**
|
||||
- Shows dog's ancestry tree
|
||||
- 5 generations displayed
|
||||
- Color-coded by sex:
|
||||
- Blue nodes = Males ♂
|
||||
- Pink nodes = Females ♀
|
||||
|
||||
### Navigating the Tree
|
||||
|
||||
#### Zoom Controls
|
||||
- **Zoom In**: Click "+" button or mouse wheel up
|
||||
- **Zoom Out**: Click "-" button or mouse wheel down
|
||||
- **Reset View**: Click reset button to center tree
|
||||
|
||||
#### Panning
|
||||
- **Click and Drag**: Move the tree around
|
||||
- **Mouse Wheel**: Zoom in/out
|
||||
|
||||
#### Node Information
|
||||
Each node displays:
|
||||
- Dog name (large text)
|
||||
- Registration number
|
||||
- Birth year
|
||||
- Sex symbol (♂ or ♀)
|
||||
|
||||
### Reading the Tree
|
||||
|
||||
```
|
||||
Great-Great-Grandpa ♂
|
||||
Great-Grandpa ♂
|
||||
Great-Great-Grandma ♀
|
||||
Grandpa ♂
|
||||
Great-Great-Grandpa ♂
|
||||
Great-Grandma ♀
|
||||
Great-Great-Grandma ♀
|
||||
Sire ♂
|
||||
Great-Great-Grandpa ♂
|
||||
Great-Grandpa ♂
|
||||
Great-Great-Grandma ♀
|
||||
Grandma ♀
|
||||
Great-Great-Grandpa ♂
|
||||
Great-Grandma ♀
|
||||
Great-Great-Grandma ♀
|
||||
Dog Name
|
||||
Dam ♀
|
||||
[... similar structure for dam's side]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: Breeding a Litter
|
||||
|
||||
1. ✓ Select breeding pair (sire and dam)
|
||||
2. ✓ Create litter record with breeding date
|
||||
3. ✓ Track whelping date when puppies are born
|
||||
4. ✓ Add each puppy:
|
||||
- Link to the litter
|
||||
- Enter individual details
|
||||
- Assign registration numbers
|
||||
5. ✓ View pedigree of any puppy to see full ancestry
|
||||
|
||||
### Workflow 2: Recording Historical Dogs
|
||||
|
||||
1. ✓ Add foundation dogs (no parents)
|
||||
2. ✓ Add their offspring using manual parent selection
|
||||
3. ✓ Continue building the family tree
|
||||
4. ✓ View pedigrees to verify relationships
|
||||
|
||||
### Workflow 3: Planning a Breeding
|
||||
|
||||
1. ✓ View pedigrees of potential sire and dam
|
||||
2. ✓ Check for common ancestors
|
||||
3. ✓ Use trial pairing tool (coming soon)
|
||||
4. ✓ Create litter when breeding occurs
|
||||
|
||||
---
|
||||
|
||||
## Tips & Best Practices
|
||||
|
||||
### For Litter Management
|
||||
|
||||
✅ **Do:**
|
||||
- Create the litter record BEFORE adding puppies
|
||||
- Enter accurate breeding dates for record keeping
|
||||
- Use meaningful notes (progesterone timing, heat cycle info)
|
||||
- Link puppies to litters for automatic parent relationships
|
||||
|
||||
❌ **Don't:**
|
||||
- Don't change sire/dam after litter creation (create new litter instead)
|
||||
- Don't forget to update whelping date when puppies arrive
|
||||
- Avoid mixing litter-linked and manually-parented puppies
|
||||
|
||||
### For Pedigree Viewing
|
||||
|
||||
✅ **Do:**
|
||||
- Zoom out to see the full tree at once
|
||||
- Use drag to focus on specific branches
|
||||
- Click nodes to see additional details
|
||||
- Reset view if you get lost
|
||||
|
||||
❌ **Don't:**
|
||||
- Don't try to edit from pedigree view (use dog edit form)
|
||||
- Avoid excessive zooming (can make nodes too small)
|
||||
|
||||
### Data Entry Tips
|
||||
|
||||
1. **Registration Numbers**: Enter consistently (e.g., "AKC-12345")
|
||||
2. **Microchips**: Use full 15-digit number
|
||||
3. **Birth Dates**: Critical for age calculations and sorting
|
||||
4. **Breed Names**: Keep consistent spelling and capitalization
|
||||
5. **Colors**: Use standard color terminology for your breed
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No such column: sire" Error
|
||||
|
||||
**Problem:** Getting this error when adding a dog
|
||||
|
||||
**Solution:**
|
||||
1. Make sure you ran the migration:
|
||||
```bash
|
||||
node server/db/migrate_litter_id.js
|
||||
```
|
||||
2. Restart the server
|
||||
3. Try again
|
||||
|
||||
### Pedigree Tree Not Loading
|
||||
|
||||
**Problem:** Pedigree modal shows "Loading..." forever
|
||||
|
||||
**Possible Causes:**
|
||||
- Dog has no parents recorded
|
||||
- Network issue
|
||||
- Server not running
|
||||
|
||||
**Solution:**
|
||||
1. Check browser console for errors
|
||||
2. Verify server is running
|
||||
3. Ensure dog has at least one parent recorded
|
||||
|
||||
### Parents Not Auto-Populating
|
||||
|
||||
**Problem:** Selected a litter but parents didn't fill in
|
||||
|
||||
**Solution:**
|
||||
1. Refresh the page
|
||||
2. Make sure litter has valid sire and dam
|
||||
3. Try selecting the litter again
|
||||
|
||||
### Can't See All Generations
|
||||
|
||||
**Problem:** Pedigree tree only shows 2-3 generations
|
||||
|
||||
**This is normal if:**
|
||||
- Older generations don't have parents recorded
|
||||
- Foundation dogs have no ancestry
|
||||
- You need to add more historical data
|
||||
|
||||
---
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
*Coming in future release*
|
||||
|
||||
- `Ctrl/Cmd + N` - New Dog
|
||||
- `Ctrl/Cmd + L` - New Litter
|
||||
- `Ctrl/Cmd + P` - View Pedigree
|
||||
- `Esc` - Close Modal
|
||||
|
||||
---
|
||||
|
||||
## Next Features Coming Soon
|
||||
|
||||
🔜 **Trial Pairing Simulator**
|
||||
- Calculate COI before breeding
|
||||
- See common ancestors
|
||||
- Risk assessment
|
||||
|
||||
🔜 **Heat Cycle Tracking**
|
||||
- Track progesterone levels
|
||||
- Breeding date recommendations
|
||||
- Calendar view
|
||||
|
||||
🔜 **PDF Pedigree Export**
|
||||
- Print-ready pedigrees
|
||||
- Custom formatting
|
||||
- Multiple generations
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Documentation:** [FEATURE_IMPLEMENTATION.md](./FEATURE_IMPLEMENTATION.md)
|
||||
- **Roadmap:** [ROADMAP.md](./ROADMAP.md)
|
||||
- **Installation:** [INSTALL.md](./INSTALL.md)
|
||||
- **README:** [README.md](./README.md)
|
||||
|
||||
---
|
||||
|
||||
## Video Tutorials
|
||||
|
||||
*Coming soon - check back for video walkthroughs of these features!*
|
||||
|
||||
1. Creating Your First Litter
|
||||
2. Adding Puppies to a Litter
|
||||
3. Navigating Pedigree Trees
|
||||
4. Advanced Breeding Records
|
||||
|
||||
---
|
||||
|
||||
## Congratulations!
|
||||
|
||||
You're now ready to use BREEDR's litter management and pedigree visualization features. Start by creating a litter or viewing a pedigree tree!
|
||||
|
||||
**Happy Breeding! 🐶**
|
||||
Reference in New Issue
Block a user