persons

The Persons submodule is the core of the CRM: a single `person` table represents both individuals and companies (discriminated by the `type` field), with company records additionally exposed through a dedicated Accounts surface (`/person/accounts`) that filters to `type: company` and adds account-specific fields such as industry, website, annual revenue and employee count. The base `person` table holds only structural fields (name, type, status, avatar). Everything else that PersonController accepts on create/update — notes, employer_company_id, owner_user_id, source, lifecycle_stage, next_action_at, score, deal_value, tags — is persisted as key/value rows in a companion person_metadata table and reassembled into the response shape by the service. This keeps the core schema stable while letting CRM-specific attributes evolve without a migration for every new field.

Ownership and lifecycle tracking are first-class concerns. Every person can be assigned an owner_user_id (gated by the admin, admin-crm, or owner-crm role) and a lifecycle_stage drawn from a sales funnel (new, contacted, qualified, proposal, negotiation, customer, lost). POST /person/:id/lifecycle-stage records the transition explicitly rather than silently overwriting the value on a generic update, which keeps a clean history for reporting. GET /person/dashboard and GET /person/reports aggregate these stage transitions and interaction logs into funnel metrics and time-bucketed reports (day/week/month/year), giving the admin panel its pipeline visualizations without separate data warehousing.

Interactions (call, email, whatsapp, meeting, note) and follow-ups (a scheduled next_action_at plus notes) are logged per person and also surfaced as cross-person worklist endpoints — GET /person/followups and GET /person/activities return paginated, filterable views across the whole CRM so a rep can work a queue without opening every person record individually. Activities are a separate, more structured concept than interactions: they carry status and can be explicitly completed via POST /person/activities/:id/complete.

Duplicate prevention and consolidation are handled by two complementary endpoints. GET /person/duplicates performs a fuzzy check by name, email or phone before a new record is created. POST /person/merge consolidates an existing duplicate pair: contacts, documents, addresses and metadata are merged into the target record inside a single transaction, the source person is marked inactive, and a merged_into_person_id metadata pointer is left behind for traceability. Only persons of the same type can be merged, and only the contact_only strategy is currently implemented — the DTO's strategy field is typed for future strategies but the service only accepts this one value today.

Bulk onboarding is supported via a two-step CSV flow: POST /person/import/preview parses the uploaded file and returns headers and sample rows so the caller can build a column mapping, then POST /person/import applies that mapping (passed as a JSON string in a multipart field) to create person records, optionally associating them all with a company via company_id. Both endpoints reject non-CSV uploads and cap file size at 10 MB.

GET /person/avatar/:id is the one public, unauthenticated endpoint in the submodule — it serves a person's avatar image by file ID with ETag-based caching (If-None-Match) so the admin panel and any embedded widgets can render avatars without needing a session token. Linking a person to a platform user account (user_id) is restricted to a dedicated person-user-linker role in addition to admin/admin-crm, since it grants that user visibility tied to the CRM record.