Add verification checklist for future installations
This commit is contained in:
304
docs/VERIFICATION_CHECKLIST.md
Normal file
304
docs/VERIFICATION_CHECKLIST.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# BREEDR Verification Checklist
|
||||
|
||||
## Microchip Field Fix Verification
|
||||
|
||||
### ✅ Schema Files (All Correct)
|
||||
|
||||
#### 1. Database Schema: `server/db/init.js`
|
||||
- [x] **Line 29:** `microchip TEXT,` (no UNIQUE constraint)
|
||||
- [x] **Lines 38-43:** Partial unique index created
|
||||
```sql
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS idx_dogs_microchip
|
||||
ON dogs(microchip)
|
||||
WHERE microchip IS NOT NULL
|
||||
```
|
||||
|
||||
**Status:** ✅ Correct for future installations
|
||||
|
||||
---
|
||||
|
||||
#### 2. UI Form: `client/src/components/DogForm.jsx`
|
||||
- [x] **Line 150:** Microchip input has NO `required` attribute
|
||||
- [x] Label shows "Microchip Number" (no asterisk)
|
||||
- [x] Field is truly optional in the UI
|
||||
|
||||
**Status:** ✅ Correct - users can leave microchip blank
|
||||
|
||||
---
|
||||
|
||||
#### 3. Migration Script: `server/db/migrate_microchip.js`
|
||||
- [x] Exists and is executable
|
||||
- [x] Safely migrates existing databases
|
||||
- [x] Idempotent (can run multiple times)
|
||||
- [x] Preserves all data during migration
|
||||
|
||||
**Status:** ✅ Available for existing installations
|
||||
|
||||
---
|
||||
|
||||
#### 4. Migration Helper: `migrate-now.sh`
|
||||
- [x] Shell script for easy execution
|
||||
- [x] Checks if container is running
|
||||
- [x] Runs migration inside container
|
||||
- [x] Restarts container after migration
|
||||
|
||||
**Status:** ✅ User-friendly migration tool
|
||||
|
||||
---
|
||||
|
||||
#### 5. Documentation: `docs/MICROCHIP_FIX.md`
|
||||
- [x] Problem explanation
|
||||
- [x] Solution details
|
||||
- [x] Migration instructions (3 options)
|
||||
- [x] Verification tests
|
||||
- [x] Troubleshooting guide
|
||||
|
||||
**Status:** ✅ Complete documentation
|
||||
|
||||
---
|
||||
|
||||
#### 6. README: `README.md`
|
||||
- [x] Migration notice at top
|
||||
- [x] Link to detailed documentation
|
||||
- [x] Upgrade instructions included
|
||||
- [x] Recent updates section added
|
||||
|
||||
**Status:** ✅ Users will see migration notice
|
||||
|
||||
---
|
||||
|
||||
## For Future Installations
|
||||
|
||||
### Fresh Install (No Migration Needed)
|
||||
|
||||
When a user does a **fresh install** (no existing database):
|
||||
|
||||
1. Container starts
|
||||
2. `server/db/init.js` runs automatically
|
||||
3. Database created with **correct schema**
|
||||
4. Microchip field is **optional from the start**
|
||||
5. No migration required ✅
|
||||
|
||||
### Existing Installation (Migration Required)
|
||||
|
||||
When a user **upgrades** from an old version:
|
||||
|
||||
1. Pull latest code
|
||||
2. Rebuild Docker image
|
||||
3. Start container
|
||||
4. **Must run migration:** `docker exec -it breedr node server/db/migrate_microchip.js`
|
||||
5. Restart container
|
||||
6. Microchip field now optional ✅
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Test 1: Add Dog Without Microchip
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/dogs \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"TestDog1","breed":"Lab","sex":"male"}'
|
||||
```
|
||||
**Expected:** ✅ Success (201 Created)
|
||||
|
||||
### Test 2: Add Multiple Dogs Without Microchips
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/dogs \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"TestDog2","breed":"Lab","sex":"female"}'
|
||||
```
|
||||
**Expected:** ✅ Success (multiple NULL values allowed)
|
||||
|
||||
### Test 3: Add Dog With Microchip
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/dogs \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"TestDog3","breed":"Lab","sex":"male","microchip":"123456789"}'
|
||||
```
|
||||
**Expected:** ✅ Success
|
||||
|
||||
### Test 4: Duplicate Microchip Should Fail
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/dogs \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"TestDog4","breed":"Lab","sex":"female","microchip":"123456789"}'
|
||||
```
|
||||
**Expected:** ❌ Error (UNIQUE constraint still enforced for non-NULL)
|
||||
|
||||
---
|
||||
|
||||
## Database Verification
|
||||
|
||||
### Check Schema Directly
|
||||
|
||||
```bash
|
||||
# Enter container
|
||||
docker exec -it breedr sh
|
||||
|
||||
# Open SQLite CLI
|
||||
sqlite3 /app/data/breedr.db
|
||||
|
||||
# Check table schema
|
||||
.schema dogs
|
||||
|
||||
# Should show:
|
||||
# microchip TEXT, (no UNIQUE)
|
||||
|
||||
# Check indexes
|
||||
.indexes dogs
|
||||
|
||||
# Should show:
|
||||
# idx_dogs_microchip (partial index)
|
||||
|
||||
# Verify partial index
|
||||
SELECT sql FROM sqlite_master
|
||||
WHERE type='index' AND name='idx_dogs_microchip';
|
||||
|
||||
# Should show:
|
||||
# CREATE UNIQUE INDEX idx_dogs_microchip
|
||||
# ON dogs(microchip) WHERE microchip IS NOT NULL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If something goes wrong:
|
||||
|
||||
### Option A: Restore Backup
|
||||
```bash
|
||||
docker stop breedr
|
||||
cp /mnt/user/appdata/breedr/breedr.db.backup \
|
||||
/mnt/user/appdata/breedr/breedr.db
|
||||
docker start breedr
|
||||
```
|
||||
|
||||
### Option B: Re-run Migration
|
||||
```bash
|
||||
docker exec -it breedr node server/db/migrate_microchip.js
|
||||
docker restart breedr
|
||||
```
|
||||
|
||||
### Option C: Fresh Database (Data Loss)
|
||||
```bash
|
||||
docker stop breedr
|
||||
rm /mnt/user/appdata/breedr/breedr.db
|
||||
docker start breedr
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Verification
|
||||
|
||||
After deploying to production:
|
||||
|
||||
- [ ] Check container logs for schema initialization
|
||||
- [ ] Verify database schema with SQLite CLI
|
||||
- [ ] Test adding dog without microchip via UI
|
||||
- [ ] Test adding dog with microchip via UI
|
||||
- [ ] Confirm no UNIQUE constraint errors
|
||||
- [ ] Verify partial index exists
|
||||
- [ ] Test duplicate microchip still fails
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Still Getting UNIQUE Constraint Error
|
||||
|
||||
**Cause:** Migration not run on existing database
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
docker exec -it breedr node server/db/migrate_microchip.js
|
||||
docker restart breedr
|
||||
```
|
||||
|
||||
### Issue: Migration Script Not Found
|
||||
|
||||
**Cause:** Old code still in container
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
cd /mnt/user/appdata/breedr-build
|
||||
git pull
|
||||
docker build -t breedr:latest .
|
||||
docker stop breedr && docker rm breedr
|
||||
# Recreate container with new image
|
||||
```
|
||||
|
||||
### Issue: Microchip Required in UI
|
||||
|
||||
**Cause:** Browser cached old JavaScript
|
||||
|
||||
**Solution:**
|
||||
- Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
|
||||
- Clear browser cache
|
||||
- Try incognito/private window
|
||||
|
||||
---
|
||||
|
||||
## File Manifest
|
||||
|
||||
### Core Files (Must Be Present)
|
||||
- ✅ `server/db/init.js` - Database schema (corrected)
|
||||
- ✅ `server/db/migrate_microchip.js` - Migration script
|
||||
- ✅ `client/src/components/DogForm.jsx` - UI form (microchip optional)
|
||||
- ✅ `migrate-now.sh` - Helper script
|
||||
- ✅ `docs/MICROCHIP_FIX.md` - Detailed documentation
|
||||
- ✅ `docs/VERIFICATION_CHECKLIST.md` - This file
|
||||
- ✅ `README.md` - Updated with migration notice
|
||||
|
||||
### Validation Commands
|
||||
|
||||
```bash
|
||||
# Check all files exist
|
||||
ls -la server/db/init.js
|
||||
ls -la server/db/migrate_microchip.js
|
||||
ls -la client/src/components/DogForm.jsx
|
||||
ls -la migrate-now.sh
|
||||
ls -la docs/MICROCHIP_FIX.md
|
||||
ls -la docs/VERIFICATION_CHECKLIST.md
|
||||
|
||||
# Verify microchip field in init.js
|
||||
grep -n "microchip TEXT" server/db/init.js
|
||||
# Should show line 29 with NO UNIQUE
|
||||
|
||||
# Verify partial index
|
||||
grep -A2 "idx_dogs_microchip" server/db/init.js
|
||||
# Should show WHERE clause
|
||||
|
||||
# Verify form has no required
|
||||
grep -n 'name="microchip"' client/src/components/DogForm.jsx
|
||||
# Should NOT have required attribute
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
- [x] Schema file correct (no UNIQUE on microchip)
|
||||
- [x] Partial index created (WHERE IS NOT NULL)
|
||||
- [x] UI form allows empty microchip
|
||||
- [x] Migration script tested
|
||||
- [x] Documentation complete
|
||||
- [x] README updated
|
||||
- [x] Tests passing
|
||||
|
||||
### Post-Deployment Checklist
|
||||
- [ ] Container started successfully
|
||||
- [ ] Schema verified in database
|
||||
- [ ] UI allows empty microchip
|
||||
- [ ] Multiple NULL values work
|
||||
- [ ] Unique constraint still enforced for non-NULL
|
||||
- [ ] No errors in logs
|
||||
|
||||
---
|
||||
|
||||
**Last Verified:** March 8, 2026
|
||||
|
||||
**Status:** ✅ All files correct for future installations
|
||||
|
||||
**Migration Required:** Only for existing databases (one-time)
|
||||
Reference in New Issue
Block a user