# Migration: Checklist & Troubleshooting

> Referenced from `steps/step-06-migration.md` — Migration verification and common issues.

---

## Pre-Migration Build Verification (BLOCKING)

**CRITICAL:** The backend MUST build successfully before creating a migration.
EF Core tools compile the project internally; a build failure produces confusing errors
that do not point to the actual source file.

```bash
dotnet build {SolutionName}.sln --no-restore
```

**Common causes at this stage:**
- Missing DbSet registration (should have been caught in step-04 Check 2)
- Missing DI registration (should have been caught in step-04 Check 3)
- Circular references between generated services
- Missing package references (e.g., FluentValidation)
- Frontend changes that modified shared files

**After build succeeds:** Continue to migration name suggestion.

---

## Migration Content Verification

The migration should include:
- Navigation entity (Application/Module/Section/Resource)
- Navigation translations (4 languages)
- Permissions (CRUD + wildcard)
- RolePermissions (role assignments)
- Domain entity table
- Indexes and constraints
- SQL Objects: applied automatically at startup (no migration injection needed)

---

## SQL Objects

SQL objects (TVFs, views, stored procedures) are applied **automatically at application startup** via `SqlObjectHelper.ApplyAllAsync()` in `SmartStackExtensions.InitializeSmartStackAsync()`. No injection into migrations is needed — just restart the application after modifying `.sql` files.

---

## Troubleshooting

### Common Issues

| Issue | Solution |
|-------|----------|
| Migration conflicts | Run `/efcore conflicts` to analyze |
| Permission 403 errors | Verify Permissions.cs and PermissionConfiguration.cs are in sync |
| Navigation not visible | Check user role has appropriate permissions |
| Route not found | Verify nested route structure in routes.tsx |
| i18n missing | Check locale files exist and are properly loaded |
| EF Core compilation error | Check DbSet and DI registration |
| FK constraint errors | Verify all entity references exist in seed data |

### Quick Fixes

```bash
# Rebuild and restart
dotnet build
dotnet ef database update

# Clear frontend cache
cd web && rm -rf node_modules/.cache && npm run dev

# Reset database (development only)
dotnet ef database drop --context CoreDbContext --force
dotnet ef database update --context CoreDbContext
```

---

## Final Checklist

- [ ] Pre-migration build passed
- [ ] Migration name suggested via MCP
- [ ] Migration created with correct context
- [ ] Migration includes navigation, permissions, and entity table
- [ ] Migration applied successfully
- [ ] Database updated without errors
- [ ] DbSet registered in DbContext
- [ ] DI registration in place
- [ ] Application starts without errors
