# Legacy Import Foundation Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the Phase 1 legacy import foundation for staging, validation, classification, dry-run review, and admin inspection using a read-only external legacy database connection.

**Architecture:** Add a bounded `LegacyImport` module that reads legacy rows through a source-reader abstraction, stages them in dedicated tables, validates and classifies them with deterministic rules, and exposes review-friendly admin pages and commands. This phase explicitly avoids any writes into active user, CRM, enrollment, payment, attendance, or WhatsApp workflows.

**Tech Stack:** Laravel 12, Livewire 3, MySQL/PostgreSQL-compatible migrations, PHPUnit feature tests, Spatie permissions, existing Algeria phone normalization service.

---

## File Structure

### New domain area

```text
app/Domain/LegacyImport/
  Actions/
  Data/
  Queries/
  Services/
  Support/
```

### New persistence and UI areas

```text
app/Models/LegacyImportRun.php
app/Models/LegacyStudentImport.php
app/Models/LegacyTrainingImport.php
app/Models/LegacyCourseMapping.php
app/Models/LegacySessionMapping.php
app/Models/LegacyImportCommitLog.php

app/Livewire/Admin/LegacyImports/
resources/views/livewire/admin/legacy-imports/

database/migrations/*_create_legacy_import_tables.php
config/legacy-import.php
```

### Tests

```text
tests/Feature/LegacyImport/
```

## Task 1: Add legacy import schema and models

**Files:**
- Create: `database/migrations/2026_05_24_120000_create_legacy_import_tables.php`
- Create: `app/Models/LegacyImportRun.php`
- Create: `app/Models/LegacyStudentImport.php`
- Create: `app/Models/LegacyTrainingImport.php`
- Create: `app/Models/LegacyCourseMapping.php`
- Create: `app/Models/LegacySessionMapping.php`
- Create: `app/Models/LegacyImportCommitLog.php`
- Test: `tests/Feature/LegacyImport/LegacyImportSchemaTest.php`

## Task 2: Add config and source-reader foundation

**Files:**
- Create: `config/legacy-import.php`
- Create: `app/Domain/LegacyImport/Services/LegacySourceReader.php`
- Create: `app/Domain/LegacyImport/Services/DatabaseLegacySourceReader.php`
- Test: `tests/Feature/LegacyImport/LegacyImportSourceReaderTest.php`

## Task 3: Build import run and staging ingestion actions

**Files:**
- Create: `app/Domain/LegacyImport/Actions/StartLegacyImportRunAction.php`
- Create: `app/Domain/LegacyImport/Actions/IngestLegacyReferenceDataAction.php`
- Create: `app/Domain/LegacyImport/Actions/IngestLegacyStudentsAction.php`
- Create: `app/Domain/LegacyImport/Data/LegacyImportOptionsData.php`
- Test: `tests/Feature/LegacyImport/LegacyImportIngestionTest.php`

## Task 4: Add phone/email normalization and duplicate hint support

**Files:**
- Create: `app/Domain/LegacyImport/Support/LegacyEmailSanitizer.php`
- Create: `app/Domain/LegacyImport/Support/LegacyDuplicateDetector.php`
- Create: `app/Domain/LegacyImport/Data/LegacyDuplicateResultData.php`
- Modify: `app/Domain/Identity/Phone/PhoneNormalizer.php` only if extension is truly required; otherwise consume as-is
- Test: `tests/Feature/LegacyImport/LegacyNormalizationAndDuplicateTest.php`

## Task 5: Add validation and classification services

**Files:**
- Create: `app/Domain/LegacyImport/Services/LegacyStudentImportValidator.php`
- Create: `app/Domain/LegacyImport/Services/LegacyStudentImportClassifier.php`
- Create: `app/Domain/LegacyImport/Actions/ValidateLegacyStudentImportAction.php`
- Create: `app/Domain/LegacyImport/Actions/ClassifyLegacyStudentImportAction.php`
- Test: `tests/Feature/LegacyImport/LegacyClassificationTest.php`

## Task 6: Add mapping and dry-run query foundations

**Files:**
- Create: `app/Domain/LegacyImport/Queries/LegacyStudentImportListQuery.php`
- Create: `app/Domain/LegacyImport/Queries/LegacyCourseMappingListQuery.php`
- Create: `app/Domain/LegacyImport/Queries/LegacySessionMappingListQuery.php`
- Create: `app/Domain/LegacyImport/Actions/BuildLegacyDryRunReportAction.php`
- Test: `tests/Feature/LegacyImport/LegacyDryRunReportTest.php`

## Task 7: Add commands for import, validate, classify, and dry-run

**Files:**
- Create: `app/Console/Commands/LegacyImportCommand.php`
- Create: `app/Console/Commands/LegacyValidateCommand.php`
- Create: `app/Console/Commands/LegacyClassifyCommand.php`
- Create: `app/Console/Commands/LegacyDryRunCommand.php`
- Test: `tests/Feature/LegacyImport/LegacyImportCommandsTest.php`

## Task 8: Add admin review UI foundations

**Files:**
- Create: `app/Livewire/Admin/LegacyImports/RunsIndexPage.php`
- Create: `app/Livewire/Admin/LegacyImports/RunDetailPage.php`
- Create: `app/Livewire/Admin/LegacyImports/StudentsIndexPage.php`
- Create: `app/Livewire/Admin/LegacyImports/ReviewQueuePage.php`
- Create: `app/Livewire/Admin/LegacyImports/CourseMappingPage.php`
- Create: `app/Livewire/Admin/LegacyImports/SessionMappingPage.php`
- Create: `resources/views/livewire/admin/legacy-imports/*.blade.php`
- Modify: `routes/web.php`
- Modify: `resources/views/components/portal/sidebar.blade.php` if admin navigation should expose the module
- Test: `tests/Feature/LegacyImport/LegacyImportAdminUiTest.php`

## Task 9: Add permissions, masking, and policy checks

**Files:**
- Modify: `app/Support/Rbac/PermissionCatalog.php`
- Modify: `database/seeders/RolesAndPermissionsSeeder.php`
- Create: `app/Policies/LegacyStudentImportPolicy.php`
- Test: `tests/Feature/LegacyImport/LegacyImportSecurityTest.php`

## Task 10: Add operational documentation

**Files:**
- Create: `docs/legacy_platform_migration.md`

## Task 11: Final verification

**Files:**
- No code changes unless verification reveals a legitimate issue

Run:

```bash
php artisan test tests/Feature/LegacyImport
php artisan app:architecture-check
```

Expected:

- new legacy import feature tests pass
- architecture baseline does not introduce new forbidden coupling
- no active business writes from legacy import phase