# Phase: Customer Management

| Field | Value |
| --- | --- |
| Identifier | `beauty-business-14-4` |
| Status | Planned |
| Owner | Platform |
| Module(s) | `beauty_business.customers`, `beauty_business.customer_preferences`, `beauty_business.visit_history` |
| Service(s) | `beauty_business` |
| Depends On | `beauty-business-14-0`, `beauty-business-14-1` (visit refs) |
| ADR(s) | TBD |
| Manifest | [phase-manifest.yaml](../../ai-framework/phase-manifest.yaml) |
| Framework | [ADR-013](../../architecture/adr/ADR-013.md) · [ADR-018](../../architecture/adr/ADR-018.md) · [ADR-019](../../architecture/adr/ADR-019.md) |

## Objective

Manage **beauty customers** in module context: profiles linked to CRM contact refs, preferences (stylist, allergies/sensitivities notes for beauty context only, communication opt-in), visit history shells, and customer portal API contracts — without owning CRM Contact aggregates or Healthcare patient records.

## Enterprise Phase Discovery

> **Required before Implementation.**

### Target Responsibility (this phase when Complete)

- CustomerProfile with `crm_contact_ref` and optional `identity_user_ref`
- CustomerPreference (preferred stylist, notes, marketing opt-in flags)
- VisitHistoryEntry (refs completed appointments; summary only)
- CustomerDocumentRef (storage ref for patch tests, consent forms — beauty context)
- Events: `beauty_business.customer.*`
- Permissions: `beauty_business.customers.*`

### Explicitly Excluded

- CRM Lead/Contact CRUD (CRM service)
- Loyalty Member ledger (Loyalty service)
- Healthcare Patient / medical records
- Frontend customer portal UI

## Business Analysis

| Item | Detail |
| --- | --- |
| Actors | Receptionist, stylist, customer (self-service APIs) |
| Business capabilities | Register customers, track preferences, view visit summary |
| Success metrics | CRM ref integrity; no duplicate CRM ownership |
| Non-goals | Full Customer360 platform |

## Scope

### In Scope

- CustomerProfile, CustomerPreference, VisitHistoryEntry, CustomerDocumentRef
- Search/filter customers for reception workflows
- Link appointments (14.1) to customer profile

### High-Level Entities

| Entity | Purpose |
| --- | --- |
| CustomerProfile | Beauty-context customer |
| CustomerPreference | Stylist, notes, opt-ins |
| VisitHistoryEntry | Completed visit summary |
| CustomerDocumentRef | Consent / patch test file ref |

## Out of Scope

- CRM contact creation logic (call CRM API or store ref only)
- Loyalty enrollment (14.7)
- Packages (14.5)
- Healthcare patient portal and PHI

## Completion Criteria

- [ ] Customer module with CRM refs only — no CRM model imports
- [ ] Visit history references appointments, does not duplicate booking engine
- [ ] Healthcare patient module untouched

## Related Documents

- [Phase 14.1](phase-14-1-booking-engine.md)
- [Beauty Business Roadmap](../../beauty-business-roadmap.md)
- [CRM module registry](../../module-registry.md#crm)