# Designation Admin Interface - User Guide

## Overview

The Designation Admin Interface allows administrators to create and manage client designations with automatic synchronization from AMS360/AFW.

## Key Concepts

### Designations are Created in Horizon

**All designations are created and managed within the Horizon application.** They are NOT imported from AFW. Instead:

1. **Create a designation** in Horizon (e.g., "Shape", "Premium", "VIP")
2. **Optionally map it to an AFW ANotId** (a GUID that identifies customers in AMS360)
3. **Sync to automatically assign** clients based on their AFW data

### AFW ANotId Mapping

Each designation can have an **optional AFW ANotId** field:
- This is a GUID from AMS360/AFW (e.g., `13CF7DCB-F6AF-42C2-A7AB-26641A216A81`)
- It identifies a group of customers in the AFW database
- When you sync, clients with this ANotId in AFW get assigned to this designation in Horizon

### Example Workflow

```
1. Admin creates "Shape" designation in Horizon
   - Name: Shape
   - Color: Indigo
   - AFW ANotId: 13CF7DCB-F6AF-42C2-A7AB-26641A216A81

2. Admin clicks "Preview" to see which AFW customers match
   - Shows: 150 customers found in AFW with this ANotId

3. Admin saves the designation

4. Admin clicks "Sync" on the Shape designation
   - Horizon queries AFW for customers with ANotId 13CF7DCB-...
   - Finds matching clients in local database
   - Updates their designationId to "Shape"
   - Result: 145 clients updated, 5 skipped (already had Shape)

5. Admin creates "Premium" designation
   - Name: Premium
   - Color: Gold
   - AFW ANotId: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (different GUID)
   - Syncs separately from Shape
```

## Features

### Create/Edit Designations
- **Name**: Display name (e.g., "Shape", "Premium")
- **Description**: Purpose of the designation
- **Color**: Visual identifier in the UI
- **Display Order**: Sort order in lists
- **AFW ANotId**: Optional GUID for AFW sync
- **Active Status**: Enable/disable without deleting

### Preview Before Saving
- Enter an AFW ANotId
- Click the eye icon to preview
- See how many customers in AFW match
- View sample customer names
- Helps verify you have the correct GUID

### Individual Sync
- Click "Sync" on any designation with an ANotId
- Syncs only that designation
- Shows results: updated, skipped, not found

### Bulk Sync
- Click "Sync All Designations"
- Syncs all active designations that have an ANotId configured
- Shows summary results for each designation

### Uniqueness Constraints
- **Designation names** must be unique
- **AFW ANotId values** must be unique (one designation per ANotId)
- Prevents conflicts and duplicate mappings

## API Endpoints

### GET /api/admin/designations
List all designations with client counts

### POST /api/admin/designations
Create a new designation

### GET /api/admin/designations/[id]
Get a specific designation

### PATCH /api/admin/designations/[id]
Update a designation

### DELETE /api/admin/designations/[id]
Soft delete (deactivate) a designation

### POST /api/admin/designations/preview
Preview AFW customers for an ANotId

### POST /api/admin/sync-designations
Sync a single designation by ID or type

### POST /api/admin/sync-designations/bulk
Sync all active designations with ANotId configured

## Database Schema

```prisma
model Designation {
  id           String   @id @default(cuid())
  name         String   @unique
  description  String?
  color        String
  rules        String?
  displayOrder Int
  isActive     Boolean  @default(true)
  afwAnotId    String?  @unique  // Maps to AFW ANotId
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  clientsDesignation1 Client[] @relation("ClientDesignation1")
  clientsDesignation2 Client[] @relation("ClientDesignation2")
  taskTemplates       TaskTemplate[]
}
```

## Common Questions

**Q: Where do I find the AFW ANotId?**
A: Query the AFW database directly or ask your AMS360 administrator. It's a GUID that identifies customer groups.

**Q: Can I have multiple designations with the same ANotId?**
A: No, each ANotId must be unique to prevent conflicts.

**Q: What happens if I sync without an ANotId?**
A: The sync will fail with an error. ANotId is required for AFW sync.

**Q: Can I create designations without AFW sync?**
A: Yes! Leave the AFW ANotId field empty. You can manually assign clients to these designations.

**Q: What's the difference between Shape and other designations?**
A: Nothing! Shape is just a designation like any other. It happens to map to a specific ANotId in AFW.

**Q: Can I change the ANotId after creating a designation?**
A: Yes, edit the designation and update the ANotId field. Then sync again.

**Q: What happens to clients when I delete a designation?**
A: The designation is deactivated (soft delete). Clients keep their assignment, but the designation won't appear in new assignment lists.