Initial Ladill Queue release — enterprise QMS standalone app.

Phases 1–6: tickets, counters, displays, appointments, workflows, rules, analytics, reports, feedback, admin, device API, and Gitea deploy workflow for queue.ladill.com. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-29 20:19:52 +00:00
commit cca98eefd2
297 changed files with 27263 additions and 0 deletions
@@ -0,0 +1,78 @@
+# 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.