Phase 3 of Migration

strategies/DATABASE_MIGRATION.md

@@ -467,8 +467,8 @@ backend/
 |-------|-------------|--------|
 | 0     | Schema foundation (all tables in Postgres) | **COMPLETE** — applied on VPS 2026-04-17 |
 | 1     | SQLite → Postgres (data migration) | **COMPLETE** — all 12 scripts ran successfully on VPS 2026-04-17 |
-| 2     | Firestore → Postgres (data migration) | **IN PROGRESS** — scripts written, not yet run |
-| 3     | Staff auth cutover | NOT STARTED |
+| 2     | Firestore → Postgres (data migration) | **COMPLETE** — all 5 scripts ran successfully on VPS 2026-04-17 |
+| 3     | Staff auth cutover | **COMPLETE** — Postgres auth live 2026-04-17 |
 | 4     | Audit log system | NOT STARTED |
 | 5     | MQTT live data cutover | NOT STARTED |
 
@@ -546,3 +546,35 @@ docker compose exec backend python -m migration.migrate_crm_customers
 # 2.5  (depends on 2.4)
 docker compose exec backend python -m migration.migrate_crm_orders
 ```
+
+---
+
+## Phase 3 — Run Order & Commands
+
+Apply the new Alembic revision first (adds `ui_prefs` column + makes `permissions` nullable):
+
+```bash
+# Apply schema change
+docker compose exec backend alembic upgrade head
+
+# 3.1 — migrate Firestore admin_users → Postgres staff table
+docker compose exec backend python -m migration.migrate_staff
+
+# Verify
+docker compose exec postgres psql -U bellsystems_user -d bellsystems_db \
+  -c "SELECT id, email, role, is_active FROM staff ORDER BY role, name;"
+```
+
+After verifying the staff table is populated correctly:
+
+```bash
+# Restart the backend so it picks up the new auth/staff code
+docker compose restart backend
+```
+
+Then test: log in as each role in the Console UI and verify permissions work.
+
+After 24h stable operation, Firestore reads from auth are fully removed (already done in code).
+
+**Rollback:** revert `auth/router.py`, `auth/dependencies.py`, `staff/service.py`, `staff/router.py`
+to the Firestore versions — the JWT payload is unchanged so tokens remain valid during rollback.