👤 Contact Manager
Full contact/user management with role-based access, photo uploads, and multi-entity linking.
contact_roles. You only see contacts assigned to your active entity.
📋 What does this system do?
The Contact Manager manages contacts, customers, and team members across business entities. It provides:
- Session + active-entity authentication (each user belongs to one or more entities).
- Full contact lifecycle: create, view, edit, delete — with search and filters (status, gender, role, keyword).
- Photo/avatar upload, with sensible fallback defaults.
- Role assignment per entity via the
contact_rolespivot table (user_id,entity_id,role). - Live statistics: total, active, verified, primary-owner counts.
🖱️ How to Use
Login & entity context
After login, the system uses your active business_entities selection. Every contact shown belongs to that entity.
View & filter contacts
The table shows photo, name, email, phone, role and status. Filter by name/email/phone, status, gender, or role.
Add a contact
Fill in name, surname, email (required), optionally a photo and a role. New contacts get linked to your entity via contact_roles.
Edit / view / delete
Deleting only removes the contact from your entity — the contact itself is only fully deleted if it has no other entity associations left.
Deduplication
Adding a contact whose email/RFC/CURP already exists doesn't create a duplicate — it links the existing contact to your entity instead.
⭐ Core Features
| Feature | Description |
|---|---|
| 📤 Photo/Avatar upload | PNG/JPG, stored under /media/platform/img/users/ with username-based filenames. |
| 🪪 RFC/CURP validation | Uniqueness enforced at the application level — prevents duplicate official IDs across entities. |
| 🏢 Multi-entity architecture | A contact can belong to multiple entities, with a different role in each, via contact_roles. |
| 🔑 Password hashing | New contacts get a hashed password (password_hash()). Editing never shows or resets it accidentally. |
| 📊 Live statistics | Aggregated counts (active/verified/primary) scoped to the active entity. |
| 🔍 Dynamic filtering | Combined search across name/email/phone/nick plus status/gender/role. |
🔌 API Endpoints
All actions require an authenticated session and an active entity.
GET ?action=get
Paginated contacts with filters, scoped to the active entity via contact_roles.
GET ?action=get&id=123
Single contact's details (only if it belongs to your active entity).
GET ?action=stats
Entity-scoped statistics: total, active, verified, primary.
POST Create contact
Validates name/email, checks for an existing contact first, then links the role.
PUT Update contact
Updates fields, handles a new photo upload, updates the entity's role.
DELETE Delete contact
Removes the contact_roles link; only deletes the contact itself if no other entity association remains.
contacts (personal data, photo, is_active), contact_roles (user_id, entity_id, role), business_entities (entity context).
🛡️ Security & Permissions
- Session enforcement: every request checks the authenticated user and active entity; unauthorized requests get redirected to login.
- Entity isolation: every query joins through
contact_rolesscoped to the activeentity_id— you can't see or edit another entity's contacts. - SQL injection protection: parameterized queries throughout, no raw string concatenation.
- Password storage: new contacts get
password_hash()— never plaintext. - Photo upload: extension allow-list, absolute filesystem paths on save to prevent directory traversal.
🔧 Troubleshooting & FAQ
"No contacts show up" or stats show 0
contact_roles has a row linking your user to that entity.Photo not uploading or showing a default avatar
"Invalid business entity" error
business_entities record. This is normally created automatically at signup — if it's missing, contact an administrator.Duplicate contacts / linking behavior
contact_roles entry for your entity.