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