isaaccladandCursor
9e2d79936c
Visitor management app with SSO, kiosk, badges, reports, and Gitea CI deploy to frontdesk.ladill.com. Co-authored-by: Cursor <cursoragent@cursor.com>
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
# Ladill CRM
|
|
|
|
The Ladill **sales CRM** at `crm.ladill.com` — a full SSO web app for managing
|
|
**contacts, leads, deals, activities and products** — *and* the shared
|
|
Customers/Leads/Products service consumed over HTTP by Ladill Invoice, Merchant,
|
|
Mini and future apps, so contact + catalog data is owned in one place and reused
|
|
everywhere.
|
|
|
|
Every record is scoped to one platform account via `owner_ref` (the user's
|
|
`public_id` / OIDC `sub`).
|
|
|
|
## App (web UI — Sign in with Ladill)
|
|
|
|
Authenticates against `auth.ladill.com` (OIDC Authorization Code + PKCE; see
|
|
`Auth\SsoLoginController`). Local session is subordinate to the platform session
|
|
(`platform.session` middleware) and joins Single Logout via
|
|
`/sso/logout-frontchannel`.
|
|
|
|
- **Dashboard** — KPIs (contacts, open leads, open deals, pipeline value),
|
|
tasks due, recent activity.
|
|
- **Contacts** — the contact book, with a per-contact **timeline** (notes,
|
|
tasks, logged calls/meetings, sent email + SMS) and cross-product events
|
|
(invoices, payments, orders) pushed from sibling apps.
|
|
- **Leads** — list + **kanban board** (`new → contacted → qualified`), convert
|
|
to a contact.
|
|
- **Deals** — drag-free **pipeline** kanban across configurable stages
|
|
(`config/crm.pipeline_stages`), won/lost tracking.
|
|
- **Activities** — notes, tasks (with due dates / completion), calls, meetings.
|
|
- **Products & services** — reusable catalog items.
|
|
- **Comms** — email contacts (via the app mailer / Ladill Bird SMTP) and SMS
|
|
(Termii); each send is logged on the timeline.
|
|
- **Reports** — pipeline by stage, win rate, won value over time, leads by
|
|
status, activity mix.
|
|
|
|
## Service API (first-party, service-key auth)
|
|
|
|
Authenticate with a per-consumer service key:
|
|
`Authorization: Bearer <CRM_API_KEY_*>` (see `config/crm.php`,
|
|
`App\Http\Middleware\AuthenticateService`, alias `auth.service:crm`). Every
|
|
request must pass `owner` (query or body) to scope data to the end user.
|
|
|
|
```
|
|
GET /api/customers?owner=<sub>&search=
|
|
POST /api/customers {owner,name,email,phone,company,...}
|
|
... (show/update/destroy)
|
|
|
|
GET /api/leads?owner=<sub>&status=
|
|
POST /api/leads {owner,name,status,estimated_value_minor,...}
|
|
POST /api/leads/{id}/convert {owner} -> creates/links a customer
|
|
|
|
GET /api/products?owner=<sub>&type=&active=
|
|
POST /api/products {owner,name,type,unit_price_minor,currency,tax_rate}
|
|
|
|
POST /api/timeline {owner,event,title,external_id,amount_minor,
|
|
currency,url,customer_id|customer_email,...}
|
|
```
|
|
|
|
`POST /api/timeline` is how sibling products push "what happened" events onto a
|
|
contact's timeline (`invoice.sent`, `payment.received`, `order.paid`). The
|
|
`source` is derived from the service key (never client-supplied) and the write
|
|
is idempotent per `(owner, source, external_id, event)`. Reference consumer:
|
|
`ladill-invoice` `App\Services\Crm\CrmClient::pushTimeline()`.
|
|
|
|
No key → 401; missing `owner` → 422; cross-owner access → 404.
|
|
|
|
## Local dev
|
|
|
|
```bash
|
|
composer install
|
|
cp .env.example .env && php artisan key:generate
|
|
# sqlite for local: set DB_CONNECTION=sqlite and `touch database/database.sqlite`
|
|
php artisan migrate
|
|
npm install && npm run build # or `npm run dev`
|
|
php artisan serve
|
|
php artisan test
|
|
```
|
|
|
|
See `DEPLOY.md` for production cutover.
|