# Data Cleanup & Reset Tools

**Task 017** — admin-only destructive operations with preview and typed confirmation.

## Access

- **UI:** `/settings/data-cleanup` (inherits settings layout admin guard)
- **API:** `/api/admin/data-cleanup/*` — session required + `requireAdminApiSession()` (`403` for non-admin)
- Middleware: authenticated session required (`401` if not logged in)

## Safety rules

1. **Preview before execute** — `GET .../preview?scope=` returns per-collection counts.
2. **Exact confirmation phrase** — execute rejects mismatched text.
3. **Default preservation** — users, system settings, mailboxes, and email templates are **not** deleted unless `everything` scope (and users only with `includeUsers: true`).
4. **Segments preserved** on `operational_all`; deleted on `everything`.
5. **Backup recommended** — MongoDB dump before any cleanup in production.

Arabic warnings shown in UI:

- «هذا الإجراء لا يمكن التراجع عنه.»
- «لن يتم حذف المستخدمين أو الإعدادات إلا عند اختيار الحذف الكامل الصريح.»

## Scopes

| Scope | Confirmation phrase | Deletes | Preserves (default) |
|-------|---------------------|---------|---------------------|
| `market_data` | `DELETE MARKET DATA` | companies, people, contact_points, service_matches, duplicate_reviews, data_quality_issues | users, settings, mailboxes, templates, segments, operational data |
| `imports` | `DELETE IMPORT DATA` | sources, import_logs | same |
| `campaigns` | `DELETE CAMPAIGN DATA` | campaigns, campaign_recipients, email_messages, campaign-linked activities | email_templates |
| `inbox` | `DELETE INBOX DATA` | email_replies, AI classifications for replies, inbox-related activities | — |
| `leads_pipeline` | `DELETE LEADS PIPELINE DATA` | leads, opportunities, tasks, lead/opportunity activities | — |
| `notifications` | `DELETE NOTIFICATIONS` | all notifications | — |
| `operational_all` | `DELETE OPERATIONAL DATA` | market + imports + campaigns + inbox + leads/pipeline + notifications + all activities + automation_logs | users, system_settings, mailboxes, email_templates, segments |
| `everything` | `DELETE EVERYTHING` | operational_all + segments + templates + mailboxes + system_settings; optional `includeUsers` | users (unless `includeUsers: true`) |

## API

### Preview

```
GET /api/admin/data-cleanup/preview?scope=market_data
GET /api/admin/data-cleanup/preview?scope=everything&includeUsers=true
```

Response:

```json
{
  "data": {
    "scope": "market_data",
    "collections": { "companies": 2234, "people": 1974 },
    "willKeep": ["users", "system_settings", "mailboxes", "email_templates", "segments"],
    "requiredConfirmation": "DELETE MARKET DATA",
    "warning": "...",
    "includeUsersAllowed": false
  }
}
```

### Execute

```
POST /api/admin/data-cleanup/execute
```

Body:

```json
{
  "scope": "operational_all",
  "confirmation": "DELETE OPERATIONAL DATA",
  "includeUsers": false
}
```

`includeUsers` only valid when `scope` is `everything`.

## Audit

After successful execute:

- Server log: `[data-cleanup] Executed` with scope, userId, deleted counts
- In-app notification to executing admin: «تم تنفيذ تنظيف البيانات»

## Implementation

- Service: `src/server/services/data-cleanup.service.ts`
- Types: `src/types/data-cleanup.ts`
- UI: `src/components/settings/data-cleanup-client.tsx`

## Limitations

- No soft-delete or restore — hard `deleteMany` only.
- Company/person activities from market imports may remain until `operational_all` or targeted activity cleanup.
- No separate audit collection (notification + console log only).
- Segments are not removed by `operational_all` (by design).

## Related

- [11-security.md](./11-security.md)
- [18-settings-administration.md](./18-settings-administration.md)