252 lines
7.6 KiB
Markdown
252 lines
7.6 KiB
Markdown
# Deployment Checklist - Feature 002-filament-json
|
|
|
|
## Overview
|
|
This checklist covers the deployment of the Policy JSON Viewer feature to staging and production environments.
|
|
|
|
## Pre-Deployment Verification
|
|
|
|
### Code Quality ✓
|
|
- [X] All tests passing locally (Pest suite)
|
|
- [X] Code formatted with Laravel Pint
|
|
- [X] Git changes reviewed (no forbidden files modified)
|
|
- [X] Constitution compliance verified (UI-only, no behavioral changes)
|
|
|
|
### Documentation ✓
|
|
- [X] README.md updated with feature description
|
|
- [X] quickstart.md comprehensive usage guide created
|
|
- [X] research.md implementation decisions documented
|
|
- [X] tasks.md complete with traceability
|
|
|
|
---
|
|
|
|
## Staging Deployment
|
|
|
|
### 1. Code Deployment
|
|
```bash
|
|
# On local machine
|
|
git push origin tenantpilot-v1
|
|
|
|
# Dokploy will auto-deploy to staging
|
|
# Or manually trigger via Dokploy dashboard
|
|
```
|
|
|
|
### 2. Post-Deployment Commands
|
|
```bash
|
|
# SSH into staging server or use Dokploy exec
|
|
./vendor/bin/sail composer install --no-dev --optimize-autoloader
|
|
./vendor/bin/sail artisan config:clear
|
|
./vendor/bin/sail artisan view:clear
|
|
./vendor/bin/sail artisan route:clear
|
|
./vendor/bin/sail artisan cache:clear
|
|
|
|
# Verify assets published (should already exist from composer install)
|
|
ls -la public/css/pepperfm/filament-json/
|
|
```
|
|
|
|
### 3. Verification Steps
|
|
|
|
#### A. Basic Functionality
|
|
- [ ] Navigate to `/admin/policies` (policy list)
|
|
- [ ] Click any policy to view detail page
|
|
- [ ] Verify "Policy Snapshot (JSON)" section appears (or JSON tab for Settings Catalog policies)
|
|
- [ ] Verify JSON renders with pretty-print formatting
|
|
- [ ] Verify monospace font and gray background styling
|
|
- [ ] Verify scrollable container (horizontal + vertical)
|
|
|
|
#### B. Copy Functionality
|
|
- [ ] Click "Copy" button on JSON viewer
|
|
- [ ] Verify success message: "JSON copied to clipboard!"
|
|
- [ ] Paste into text editor (Cmd+V / Ctrl+V)
|
|
- [ ] Verify JSON structure intact with proper formatting
|
|
|
|
#### C. Large Payload Handling
|
|
- [ ] Find or create policy with >500 KB snapshot (512,000 bytes)
|
|
- [ ] Verify warning badge appears: "⚠️ Large payload (XXX KB). Section auto-collapsed for performance."
|
|
- [ ] Verify section collapsed by default
|
|
- [ ] Expand section, verify JSON still renders correctly
|
|
|
|
#### D. Settings Catalog Tabs
|
|
- [ ] Navigate to Settings Catalog policy (type contains "settings" or "catalog")
|
|
- [ ] Verify Tabs component appears with "Settings" and "JSON" tabs
|
|
- [ ] Click "Settings" tab → verify normalized settings table renders
|
|
- [ ] Click "JSON" tab → verify JSON viewer appears
|
|
- [ ] Verify tab switching works smoothly
|
|
|
|
#### E. Dark Mode
|
|
- [ ] Toggle dark mode in browser/Filament
|
|
- [ ] Verify JSON viewer background changes (gray-50 → gray-900)
|
|
- [ ] Verify border color adjusts (gray-200 → gray-700)
|
|
- [ ] Verify text remains readable
|
|
|
|
#### F. Browser Search
|
|
- [ ] Open JSON viewer
|
|
- [ ] Use Cmd+F (Mac) or Ctrl+F (Windows)
|
|
- [ ] Search for specific key or value in JSON
|
|
- [ ] Verify browser highlights matches within JSON container
|
|
|
|
#### G. Null/Missing Snapshot Handling
|
|
- [ ] Find policy with no versions/snapshots
|
|
- [ ] Verify message displays: "No snapshot available"
|
|
- [ ] Verify no errors in browser console
|
|
|
|
### 4. Performance Testing
|
|
```bash
|
|
# SSH into staging
|
|
./vendor/bin/sail artisan test
|
|
|
|
# Check for regressions
|
|
# Expected: Same pass/fail rate as before deployment
|
|
```
|
|
|
|
- [ ] Load policy with 100 KB snapshot → verify <1s render
|
|
- [ ] Load policy with 500 KB snapshot → verify <2s render
|
|
- [ ] Load policy with 1 MB snapshot → verify auto-collapse prevents freeze
|
|
|
|
### 5. Browser Console Check
|
|
- [ ] Open browser DevTools Console (F12 → Console tab)
|
|
- [ ] Navigate through policy detail pages
|
|
- [ ] Verify no JavaScript errors
|
|
- [ ] Verify no 404s for CSS assets
|
|
|
|
---
|
|
|
|
## Production Deployment
|
|
|
|
### Prerequisites
|
|
- [X] Staging deployment successful
|
|
- [X] All staging verification steps passed
|
|
- [X] Manual QA sign-off from stakeholder
|
|
|
|
### 1. Code Deployment
|
|
```bash
|
|
# Merge to production branch
|
|
git checkout main
|
|
git merge tenantpilot-v1
|
|
git push origin main
|
|
|
|
# Dokploy auto-deploys to production
|
|
# Or manually trigger via Dokploy dashboard
|
|
```
|
|
|
|
### 2. Post-Deployment Commands
|
|
```bash
|
|
# Same as staging
|
|
./vendor/bin/sail composer install --no-dev --optimize-autoloader
|
|
./vendor/bin/sail artisan config:clear
|
|
./vendor/bin/sail artisan view:clear
|
|
./vendor/bin/sail artisan route:clear
|
|
./vendor/bin/sail artisan cache:clear
|
|
```
|
|
|
|
### 3. Smoke Testing (Production)
|
|
- [ ] Test 3-5 representative policies (various types)
|
|
- [ ] Verify JSON viewer renders
|
|
- [ ] Verify copy functionality works
|
|
- [ ] Verify no errors in browser console
|
|
|
|
### 4. Monitor for Issues
|
|
- [ ] Check Laravel logs: `storage/logs/laravel.log`
|
|
- [ ] Monitor application performance (response times)
|
|
- [ ] Watch for user-reported issues (first 24 hours)
|
|
|
|
---
|
|
|
|
## Rollback Plan
|
|
|
|
### If Critical Issues Found
|
|
|
|
#### 1. Code Rollback
|
|
```bash
|
|
# Revert the feature branch merge
|
|
git revert <merge-commit-hash>
|
|
git push origin main
|
|
|
|
# Or reset to previous commit
|
|
git reset --hard <previous-commit-hash>
|
|
git push origin main --force
|
|
```
|
|
|
|
#### 2. Package Removal (Optional)
|
|
```bash
|
|
# If package causing issues
|
|
./vendor/bin/sail composer remove pepperfm/filament-json
|
|
./vendor/bin/sail artisan config:clear
|
|
./vendor/bin/sail artisan view:clear
|
|
|
|
# Remove published assets
|
|
rm -rf public/css/pepperfm/filament-json/
|
|
```
|
|
|
|
#### 3. Database Rollback
|
|
**Not applicable** - this feature has no migrations or database changes.
|
|
|
|
#### 4. Verify Rollback
|
|
- [ ] Policy detail pages render without JSON viewer
|
|
- [ ] Normalized settings still display correctly
|
|
- [ ] No errors in logs or browser console
|
|
|
|
---
|
|
|
|
## Deployment Timeline
|
|
|
|
### Estimated Duration
|
|
- **Staging**: ~30 minutes (deployment + verification)
|
|
- **Production**: ~20 minutes (deployment + smoke testing)
|
|
- **Total**: ~50 minutes
|
|
|
|
### Recommended Schedule
|
|
- **Staging**: Deploy during business hours for immediate testing
|
|
- **Production**: Deploy during low-traffic window (if applicable) or business hours with monitoring
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
- [X] JSON viewer renders on all policy detail pages
|
|
- [X] Copy-to-clipboard functionality works across browsers
|
|
- [X] Large payload warnings display correctly (>500 KB)
|
|
- [X] Settings Catalog tabs switch between Settings and JSON views
|
|
- [X] Dark mode styling applied correctly
|
|
- [X] Browser search (Cmd+F / Ctrl+F) works within JSON
|
|
- [X] No performance degradation (<2s render for policies up to 1 MB)
|
|
- [X] No new errors in logs or browser console
|
|
|
|
---
|
|
|
|
## Known Limitations
|
|
|
|
1. **Search Within JSON**: Relies on browser native find-in-page (Cmd+F / Ctrl+F), not a custom search UI.
|
|
2. **Download Action**: Not implemented in MVP - copy functionality deemed sufficient.
|
|
3. **Package Usage**: pepperfm/filament-json installed but not used in final implementation (native Filament approach chosen for better infolist integration).
|
|
|
|
---
|
|
|
|
## Support & Troubleshooting
|
|
|
|
### Issue: JSON not rendering
|
|
**Check**:
|
|
- Browser console for JavaScript errors
|
|
- Laravel logs for PHP errors
|
|
- Verify snapshot exists: `$record->versions()->orderByDesc('captured_at')->value('snapshot')`
|
|
|
|
### Issue: Copy button not working
|
|
**Check**:
|
|
- Browser supports Clipboard API (all modern browsers)
|
|
- HTTPS required for Clipboard API (localhost exempt)
|
|
- Check browser console for permissions errors
|
|
|
|
### Issue: Large payload freezing browser
|
|
**Check**:
|
|
- Verify payload size detection logic: `strlen(json_encode($state)) > 512000`
|
|
- Verify auto-collapse enabled for large payloads
|
|
- Consider reducing max-h-96 to max-h-64 for very large payloads
|
|
|
|
---
|
|
|
|
## Contact
|
|
|
|
For deployment issues or questions:
|
|
- **Developer**: Ahmed Darrazi
|
|
- **Documentation**: `specs/002-filament-json/quickstart.md`
|
|
- **Repository**: TenantAtlas (tenantpilot-v1 branch)
|