Account, Company & Contact Management

1. Business Summary

Maintains the customer master record (Accounts), corporate hierarchy (Companies), people (Contacts), addresses, billing/PO/invoicing options, payment behavior, branches, account teams, marketing/sales attribution, and compliance.

2. Business Value

Single source of truth for everything customer-facing: pricing, invoicing, deliveries, satisfaction.

3. Users / Stakeholders

Sales, account managers, project managers, vendor managers, finance, executives.

4. Workflows

A. Account creation & assignment
- Direct or via lead conversion.
- Sales agent (sales_agent_id), account manager (account_manager_id), PMs (project_pm_id, test_pm_id) assigned.
- Hierarchy via parent_id and root_id; invoicing via invoicing_account_id.

B. Billing/PO configuration
- Set account_invoicing_option_id, account_po_option_id, account_early_payment_option_id, actual_payment_method_id, payment_behavior_id, currency_id, price_book_id, branch_id.

C. Compliance & verification
- verification_status_id, compliant_status_id, current_status_id, last_year_status_id track regulatory and lifecycle state.

D. Customer pattern tracking
- current_pattern_id, previous_pattern_id capture buying behavior changes.

E. Account-Company relationships
- HABTM and AccountRelationship (account_from_id, account_to_id, relationship_id) for ownership, parent/child, sister-co.

5. Sub-Features

• Multi-level hierarchy (Account → Parent/Root → Invoicing Account).
• Account team (sales agent + AM + PMs + Test PM + ChecklistGroup + back-up PMs).
• Contact management with HABTM Communication Channels and emails.
• Branches per brand.
• Account references (specialized contacts/refs per account).

6. Business Rules

• BillingAddress and PrimaryAddress required for invoicing.
• PriceBook validation: name, currency_id, brand_id, entered_by, last_updated_by all numeric/non-empty.
• ContactSatisfaction tied to contact + account.

7. Data Entities

Account, Company, Contact, Address, Branch, PriceBook, ContactEmail, ContactSatisfaction, AccountRelationship, CompanyRelationship, AccountInvoicingOption, AccountPoOption, AccountEarlyPaymentOption, AccountEarlyPaymentOptionsDetail, AccountRelationships, ChecklistGroup.

8. Entry Points

• crm/accounts, crm/companies, crm/contacts, crm/branches, crm/priceBooks, crm/clientPayments.
• FreshSales sync flows: getAccounts, getContacts.

9. Inputs & Outputs

• Inputs: account profile, addresses, contacts, billing/PO settings.
• Outputs: customer master record, account team, billing config.

10. Integrations

• FreshSales (account/contact import).
• SAP (account sync — SapController::sapAccountSync).

11. Calculations / Logic

• Tax rate inferred from Branch.tax_id.
• Price source = PriceBook.currency vs. Account.currency.
• Effective AR balance = Σ ClientInvoice.amount – Σ ClientPaymentDetail.amount.

12. Status Lifecycle

• AccountStatus (active / inactive / closed / suspended).
• AccountYearStatus (current_status_id, last_year_status_id) for annual retention.
• Verification, Compliance.

13. Permissions

• Sales agent, AM, PMs, back-up PMs.
• Brand isolation.

14. Reports & KPIs

• Account growth, retention vs. churn (year-status comparison), AR aging, satisfaction score.

15. Risks & Observations

• Cyclic risk in parent_id/root_id (no validation).
• Many downstream features assume account financial config — bad data has wide impact.
• Hard-coded Currency = "##" for SAP account sync (default).

16. Source Code Evidence

• app/Plugin/crm/Model/Account.php, Company.php, Contact.php, Branch.php, AccountInvoicingOption.php, AccountPoOption.php, AccountRelationship.php, CompanyRelationship.php, ContactSatisfaction.php.
• app/Plugin/crm/Controller/AccountsController.php, CompaniesController.php, ContactsController.php, BranchesController.php, PriceBooksController.php, accountsContactsController.php.
• app/Controller/SapController.php :: sapAccountSync (~line 339).