# PILOT-002

## Guest Import Engine

You are implementing the second Pilot Launch feature for the INVEETAIRE platform.

Pilot-001 (Invitation Engine Foundation) has been completed.

Implement ONLY the Guest Import Engine.

Do NOT implement WhatsApp Distribution.

Do NOT implement RSVP.

Do NOT implement QR Check-In.

Do NOT implement Attendance Dashboard.

---

# Goal

Allow Couples to import wedding guest data from an Excel/CSV file.

The system must automatically create guest identities that will be reused by every future Pilot feature.

---

# Existing Architecture

Workspace

↓

Invitation

↓

Guests

↓

Guest Token

↓

Personal URL

↓

QR

↓

RSVP

↓

Check-In

---

# Mandatory Reading

Read:

* AI.md
* WORKFLOW.md
* IMPLEMENTATION_ROADMAP.md
* PILOT-001 implementation memory

---

# Files Allowed

Create only:

app/modules/Guest/

```
GuestController.php

GuestService.php

GuestModel.php

GuestValidator.php

GuestImporter.php

routes.php
```

Create Views:

app/views/guest/

```
import.php

import_result.php
```

Modify:

routes/couple.php

No other files.

---

# Functional Scope

Implement:

## Couple Dashboard

Guest Menu

↓

Import Guest

---

Supported File Types

* CSV
* XLSX

---

Expected Columns

Required:

* Guest Name

Optional:

* Phone Number
* Address
* Category
* Group
* Seat Number
* Pax

---

# Import Rules

For every imported guest:

Generate:

* guest_code
* guest_token

Store:

* workspace_id
* invitation_id
* guest name
* phone
* category
* group
* seat number
* pax

Default values:

attendance_status = pending

checked_in_at = NULL

RSVP = pending

Wish = empty

---

# Guest Token

Generate a secure random token.

Requirements:

* URL safe
* Cryptographically secure
* Unique
* Never derived from Guest ID
* Never derived from Guest Name

The token will become the permanent Guest identity.

Future features must reuse the same token.

---

# Import Validation

Validate:

* Duplicate rows inside uploaded file.
* Empty guest names.
* Invalid phone numbers.
* Maximum row limit.
* Duplicate guest within the same workspace.

Skip invalid rows.

Continue import.

Produce import summary.

---

# Controller

Thin.

No SQL.

No import logic.

---

# Service

Owns:

* import workflow
* duplicate detection
* token generation
* statistics

---

# Model

Owns:

All PDO queries.

Prepared statements only.

Workspace isolation mandatory.

---

# Import Result

Display:

Imported

Skipped

Duplicate

Errors

Processing time

---

# Security

Workspace isolation.

Prepared SQL.

CSRF.

escape_html().

Uploaded file validation.

Reject executable files.

Reject oversized files.

---

# Constraints

Do NOT:

* implement WhatsApp
* implement QR
* implement RSVP
* implement Public URL
* implement Guest Edit
* implement Check-In
* modify app/core/*
* modify Workspace module
* modify Invitation module
* modify database schema

---

# Verification

Verify:

CSV import.

XLSX import.

100 guests.

500 guests.

Duplicate detection.

Token uniqueness.

Workspace isolation.

PHP syntax passes.

---

# Acceptance Criteria

PASS only if:

* Guest module created.
* Import page created.
* CSV import works.
* XLSX import works.
* Duplicate detection works.
* Secure guest token generated.
* Import summary generated.
* Controller remains thin.
* Service owns import logic.
* Model owns SQL.
* PHP syntax passes.

---

# Output

Provide:

1. Files created.
2. Files modified.
3. Import workflow.
4. Token generation workflow.
5. Duplicate detection workflow.
6. Security verification.
7. Acceptance checklist.
8. PHP syntax results.

Stop after implementation.

Wait for Human Approval.