# 16 — Sales Force Automation (SFA) / CRM

**Status**: Not Started
**Depends On**: 12 — Store Management

---

## Goal

Covers the lead/interaction half of
[mainPlan.md §10](./mainPlan.md#10-sales-force-automation-sfa--crm):
`logCustomerInteraction`, `createLead`, `convertLeadToStore`. Performance/incentive functions
(`trackTargetVsAchievement`, `calculateIncentive`) are already scoped in
[08_sales_agent_controls.md](./08_sales_agent_controls.md) — not repeated here.

---

## Background / Context

There is no `Lead` entity or interaction log anywhere in the schema today — new outlet onboarding
currently goes straight to `POST /api/stores` with no pre-qualification step.

---

## Data Model Changes

### Lead

`ProspectName`, `ContactInfo`, `Notes`, `Status` (`New`, `Qualified`, `Converted`, `Rejected`),
`AssignedToUserId`.

### Customer Interaction

`StoreId` (nullable — can be logged against a `Lead` instead), `LeadId` (nullable), `UserId`,
`Notes`, `CreatedAt`.

---

## API Endpoints

| Function reference | Endpoint intent |
|---|---|
| `logCustomerInteraction(storeId, notes)` | `POST /api/stores/{id}/interactions` |
| `createLead(prospectData)` | `POST /api/leads` |
| `convertLeadToStore(leadId)` | `POST /api/leads/{id}/convert` — creates a `Store` via the existing `POST /api/stores` path internally |

---

## Business Rules

- `convertLeadToStore` reuses `createStore` (§4, [12_store_management.md](./12_store_management.md))
  rather than duplicating store-creation logic — a `Lead` conversion is not a separate creation
  path.
- Exactly one of `StoreId`/`LeadId` must be set on a `Customer Interaction` row, never both, never
  neither.

---

## Open Questions

- Does a `Lead` need its own scope/authorization model (region/route), or does it inherit the
  creating user's scope with no further restriction until converted?

---

## Implementation Notes

> Fill this section in during planning discussion before writing any code.