ADR-0001/1: pre-flight email-duplicates audit script (blocks migration 002)

[TheBoomerDev]

Summary

Add a pre-migration audit script that detects any pre-existing duplicate email values
in the users collection. ADR-0001 plans to flip the compound
{email:1, regionId:1} UNIQUE index to a single-field {email:1} UNIQUE; this
script must return an empty result before the migration is safe to execute.

Spec

The decision lives at https://github.com/cargoffer/education_backend/blob/feat/adr-0001-global-email-uniqueness/docs/adr/0001-global-email-uniqueness.md. The audit step maps to step § Implementation Plan → 1. Pre-migration audit of the ADR.

Acceptance criteria

• New file backend/scripts/audit-email-duplicates.ts that connects to the configured MongoDB (using src/config/env.ts).
• Aggregate: db.users.aggregate([{ $group: { _id: '$email', count: { $sum: 1 }, docs: { $push: { _id: '$_id', regionId: '$regionId', role: '$role' } } } }, { $match: { count: { $gt: 1 } } }]).
• Outputs:
  • stdout: human-readable table grouped by email.
  • backend/docs/migrations/0001/email-duplicates-audit.json: machine-readable array.
• Exits 0 if 0 duplicates found; exits 1 with a clear error message otherwise.
• README-block in the audit file explains how to run, how to interpret results, and what to do when duplicates are found.

Out of scope

• Migration 002 itself (issue B).
• Schema or controller changes.

Dependencies

• Independent; must complete BEFORE issue B (migration 002) ships.
• Linked from PR https://github.com/cargoffer/education_portal/pull/81's Resueltas follow-up checklist.

References

• ADR: https://github.com/cargoffer/education_backend/blob/feat/adr-0001-global-email-uniqueness/docs/adr/0001-global-email-uniqueness.md
• Context: PR feat(auth): reject duplicate emails in registration with race-condition hardening #23 (fix(auth): reject duplicate emails in registration)