dolibarr 25.0.0-alpha
navigation.class.php
1<?php
2/* Copyright (C) 2026 Laurent Destailleur <eldy@users.sourceforge.net>
3 * Copyright (C) 2026 Nick Fragoulis
4 * Copyright (C) 2026 MDW <mdeweerd@users.noreply.github.com>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <https://www.gnu.org/licenses/>.
18 */
19/* htdocs/ai/tools/navigation.php */
20
21require_once DOL_DOCUMENT_ROOT . '/core/class/extrafields.class.php';
22
29{
35 public function getDefinitions(): array
36 {
37 return [
38 [
39 "name" => "navigate_to_page",
40 "description" => "Generates a valid Dolibarr URL. Handles generic names (e.g., 'invoice' maps to customer invoices) and directory structures automatically. Can filter lists by status.",
41 "inputSchema" => [
42 "type" => "object",
43 "properties" => [
44 "object_type" => [
45 "type" => "string",
46 "description" => "The object type. Examples: 'invoice', 'thirdparty', 'order', 'proposal', 'project', 'supplier_invoice', 'website'.",
47 ],
48 "view" => [
49 "type" => "string",
50 "description" => "The type of view needed: 'list', 'card', 'create'.",
51 "enum" => ["list", "card", "create"]
52 ],
53 "id" => [
54 "type" => "integer",
55 "description" => "The ID of the record (optional)."
56 ],
57 "ref" => [
58 "type" => "string",
59 "description" => "The Reference of the record (optional)."
60 ],
61 "status_filter" => [
62 "type" => "string",
63 "description" => "A human-readable status to filter the list. Only applies to 'list' view. Examples: 'draft', 'open', 'paid', 'shipped', 'closed', 'canceled'."
64 ],
65 "params" => [
66 "type" => "object",
67 "description" => "Additional URL parameters (e.g. {'search_thirdparty': 'MyCompany'}). These will be combined with the status filter."
68 ]
69 ],
70 "required" => ["object_type", "view"]
71 ]
72 ]
73 ];
74 }
75
82 public function getRequiredRights(string $toolName)
83 {
84 return self::RIGHTS_ENFORCED_DOWNSTREAM;
85 }
86
93 public function getCategories(): array
94 {
95 return ['global'];
96 }
97
105 public function execute(string $name, array $args)
106 {
107 global $langs, $db;
108
109 // Load translation files
110 $langs->load("companies");
111 $langs->load("bills");
112 $langs->load("orders");
113 $langs->load("propal");
114 $langs->load("projects");
115 $langs->load("sendings");
116
117 if ($name !== 'navigate_to_page') {
118 return null;
119 }
120
121 if (empty($this->user->id)) {
122 return ["error" => "Permission Denied: User not logged in."];
123 }
124
125 $rawType = $args['object_type'] ?? '';
126 $view = $args['view'] ?? 'list';
127 $id = (int) ($args['id'] ?? 0);
128 $ref = $args['ref'] ?? '';
129 $statusFilter = $args['status_filter'] ?? '';
130 $params = $args['params'] ?? [];
131
132 // Resolve Logical Object to Physical Path (with Aliases)
133 $pathInfo = $this->resolvePath($rawType, $view);
134
135 if (empty($pathInfo)) {
136 return ["error" => "Unknown object type: '$rawType'. Try 'invoice', 'order', or 'thirdparty'."];
137 }
138
139 $relativePath = $pathInfo['path'];
140 $elementType = $pathInfo['type'];
141
142 // Check permissions
143 if (!$this->checkPermissions($elementType, $view, $id)) {
144 return ["error" => "Permission Denied: You don't have permission to access this resource."];
145 }
146
147 // Build Query Parameters
148 $getQueryParams = [];
149
150 // Handle Action/ID logic
151 if ($id > 0) {
152 $getQueryParams['id'] = $id;
153 } elseif (!empty($ref)) {
154 $getQueryParams['ref'] = $ref;
155 }
156
157 // Set action for create view
158 if ($view === 'create') {
159 $getQueryParams['action'] = 'create';
160 }
161
162 // The website editor uses its own parameter names
163 if ($elementType === 'website') {
164 $getQueryParams = [];
165 if ($id > 0) {
166 $getQueryParams['websiteid'] = $id;
167 } elseif (!empty($ref)) {
168 $getQueryParams['website'] = $ref;
169 }
170 if ($view === 'create') {
171 $getQueryParams['action'] = 'createsite';
172 }
173 }
174
175 // Handle Status Filtering
176 if ($view === 'list' && !empty($statusFilter)) {
177 $statusParam = $this->mapStatusToFilter($elementType, $statusFilter);
178 if ($statusParam) {
179 $getQueryParams = array_merge($getQueryParams, $statusParam);
180 } else {
181 return ["error" => "Unknown status filter '$statusFilter' for object type '$rawType'."];
182 }
183 } elseif (!empty($statusFilter)) {
184 return ["error" => "The 'status_filter' parameter can only be used with the 'list' view."];
185 }
186
187 // Merge extra params
188 if (!empty($params) && is_array($params)) {
189 $getQueryParams = array_merge($getQueryParams, $params);
190 }
191
192 // Generate Native URL
193 $baseUrl = dol_buildpath($relativePath, 1);
194
195 $finalUrl = $baseUrl;
196 if (!empty($getQueryParams)) {
197 $finalUrl .= '?' . http_build_query($getQueryParams);
198 }
199
200 return [
201 "url" => $finalUrl,
202 "description" => $this->generateDescription($elementType, $view, $id, $statusFilter),
203 "meta" => [
204 "resolved_type" => $elementType,
205 "path" => $relativePath
206 ]
207 ];
208 }
209
218 private function mapStatusToFilter($elementType, $statusFilter)
219 {
220 $statusFilter = strtolower(trim($statusFilter));
221
222 // Master map of element types to their status filters
223 $statusMap = [
224 'invoice_customer' => [
225 'draft' => ['statut' => 0],
226 'unpaid' => ['statut' => 1], // Validated but not paid
227 'paid' => ['statut' => 2],
228 ],
229 'invoice_supplier' => [
230 'draft' => ['statut' => 0],
231 'unpaid' => ['statut' => 1],
232 'paid' => ['statut' => 2],
233 ],
234 'order' => [
235 'draft' => ['statut' => 0],
236 'validated' => ['statut' => 1],
237 'shipped' => ['statut' => 2], // Or partially shipped
238 'closed' => ['statut' => 3],
239 'canceled' => ['statut' => -1],
240 ],
241 'order_supplier' => [
242 'draft' => ['statut' => 0],
243 'validated' => ['statut' => 1],
244 'approved' => ['statut' => 2],
245 'received' => ['statut' => 3], // Or partially received
246 'canceled' => ['statut' => -1],
247 ],
248 'proposal' => [
249 'draft' => ['statut' => 0],
250 'open' => ['statut' => 1],
251 'signed' => ['statut' => 2],
252 'billed' => ['statut' => 3],
253 'refused' => ['statut' => 4],
254 'canceled' => ['statut' => 5],
255 ],
256 'project' => [
257 'draft' => ['status' => 0],
258 'open' => ['status' => 1],
259 'closed' => ['status' => 2],
260 ],
261 'expedition' => [ // Shipments
262 'draft' => ['status' => 0],
263 'validated' => ['status' => 1],
264 'shipped' => ['status' => 2],
265 'canceled' => ['status' => -1],
266 ],
267 'contract' => [
268 'draft' => ['statut' => 0],
269 'active' => ['statut' => 1],
270 'closed' => ['statut' => 2],
271 'resiliated' => ['statut' => 3], // Resiliated
272 ],
273 'fichinter' => [ // Interventions
274 'draft' => ['statut' => 0],
275 'validated' => ['statut' => 1],
276 'billed' => ['statut' => 2],
277 'closed' => ['statut' => 3],
278 ],
279 // Add other object types as needed
280 ];
281
282 return $statusMap[$elementType][$statusFilter] ?? null;
283 }
284
292 private function resolvePath($input, $view)
293 {
294 $input = strtolower(trim($input));
295
296 // Normalize Aliases (Make the tool robust to LLM guessing)
297 $aliases = [
298 // Invoices
299 'invoice' => 'invoice_customer',
300 'bill' => 'invoice_customer',
301 'facture' => 'invoice_customer',
302 'supplier_invoice' => 'invoice_supplier',
303 'vendor_bill' => 'invoice_supplier',
304 // Thirdparties
305 'company' => 'thirdparty',
306 'societe' => 'thirdparty',
307 'customer' => 'thirdparty',
308 'client' => 'thirdparty',
309 'supplier' => 'thirdparty',
310 'vendor' => 'thirdparty',
311 // Commercial
312 'propal' => 'proposal',
313 'quote' => 'proposal',
314 'command' => 'order',
315 'customer_order' => 'order',
316 'supplier_order' => 'order_supplier',
317 // Products/Services
318 'product' => 'product',
319 'service' => 'product',
320 // Projects
321 'project' => 'project',
322 'task' => 'project_task',
323 // Shipping
324 'shipment' => 'expedition',
325 'shipping' => 'expedition',
326 'delivery' => 'expedition',
327 // Payments
328 'payment' => 'payment',
329 'payment_customer' => 'payment',
330 'payment_supplier' => 'payment_supplier',
331 // Banking
332 'transaction' => 'bank',
333 'account' => 'bank',
334 'bank_account' => 'bank',
335 // Events
336 'event' => 'agenda',
337 'agenda' => 'agenda',
338 'appointment' => 'agenda',
339 // Contracts
340 'contract' => 'contract',
341 // Interventions
342 'intervention' => 'fichinter',
343 // Members
344 'member' => 'adherent',
345 'membership' => 'adherent',
346 // Categories
347 'category' => 'categories',
348 // Websites
349 'site' => 'website',
350 'web_site' => 'website',
351 ];
352
353 $type = $aliases[$input] ?? $input;
354
355 // Map Normalized Types to Physical Paths
356 $map = [
357 'thirdparty' => '/societe/',
358 'contact' => '/contact/',
359 'product' => '/product/',
360 'project' => '/projet/',
361 'project_task' => '/projet/tasks/',
362 'invoice_customer' => '/compta/facture/',
363 'invoice_supplier' => '/fourn/facture/',
364 'order' => '/commande/',
365 'order_supplier' => '/fourn/commande/',
366 'proposal' => '/comm/propal/',
367 'expedition' => '/expedition/',
368 'payment' => '/compta/paiement.php', // Direct file, not directory
369 'payment_supplier' => '/fourn/paiement.php', // Direct file, not directory
370 'bank' => '/compta/bank/',
371 'agenda' => '/comm/action/',
372 'contract' => '/contrat/',
373 'fichinter' => '/fichinter/',
374 'adherent' => '/adherents/',
375 'categories' => '/categories/',
376 'website' => '/website/index.php', // Direct file: the website editor lists the sites in a selector
377 ];
378
379 if (!isset($map[$type])) {
380 return null;
381 }
382
383 $dir = $map[$type];
384
385 // Determine Script based on View
386 // Handle special cases where the path is already a file
387 if (strpos($dir, '.php') !== false) {
388 return [
389 'type' => $type,
390 'path' => $dir
391 ];
392 }
393
394 $script = 'list.php'; // Default
395
396 if ($view === 'card' || $view === 'create') {
397 $script = 'card.php';
398 }
399
400 return [
401 'type' => $type,
402 'path' => $dir . $script
403 ];
404 }
405
414 private function checkPermissions($elementType, $view, $id = 0)
415 {
416 // Default to false
417 $permitted = false;
418
419 // Check permissions based on element type
420 switch ($elementType) {
421 case 'thirdparty':
422 $permitted = $this->user->hasRight('societe', 'lire') ||
423 ($view === 'create' && $this->user->hasRight('societe', 'creer'));
424 break;
425
426 case 'contact':
427 $permitted = $this->user->hasRight('societe', 'contact->lire') ||
428 ($view === 'create' && $this->user->hasRight('societe', 'contact->creer'));
429 break;
430
431 case 'product':
432 $permitted = $this->user->hasRight('produit', 'lire') ||
433 ($view === 'create' && $this->user->hasRight('produit', 'creer'));
434 break;
435
436 case 'project':
437 $permitted = $this->user->hasRight('projet', 'lire') ||
438 ($view === 'create' && $this->user->hasRight('projet', 'creer'));
439 break;
440
441 case 'project_task':
442 $permitted = $this->user->hasRight('projet', 'lire');
443 break;
444
445 case 'invoice_customer':
446 $permitted = $this->user->hasRight('facture', 'lire') ||
447 ($view === 'create' && $this->user->hasRight('facture', 'creer'));
448 break;
449
450 case 'invoice_supplier':
451 $permitted = $this->user->hasRight('fournisseur', 'facture->lire') ||
452 ($view === 'create' && $this->user->hasRight('fournisseur', 'facture->creer'));
453 break;
454
455 case 'order':
456 $permitted = $this->user->hasRight('commande', 'lire') ||
457 ($view === 'create' && $this->user->hasRight('commande', 'creer'));
458 break;
459
460 case 'order_supplier':
461 $permitted = $this->user->hasRight('fournisseur', 'commande->lire') ||
462 ($view === 'create' && $this->user->hasRight('fournisseur', 'commande->creer'));
463 break;
464
465 case 'proposal':
466 $permitted = $this->user->hasRight('propal', 'lire') ||
467 ($view === 'create' && $this->user->hasRight('propal', 'creer'));
468 break;
469
470 case 'expedition':
471 $permitted = $this->user->hasRight('expedition', 'lire') ||
472 ($view === 'create' && $this->user->hasRight('expedition', 'creer'));
473 break;
474
475 case 'payment':
476 $permitted = $this->user->hasRight('facture', 'paiement');
477 break;
478
479 case 'payment_supplier':
480 $permitted = $this->user->hasRight('fournisseur', 'facture->paiement');
481 break;
482
483 case 'bank':
484 $permitted = $this->user->hasRight('banque', 'lire') ||
485 ($view === 'create' && $this->user->hasRight('banque', 'creer'));
486 break;
487
488 case 'agenda':
489 $permitted = $this->user->hasRight('agenda', 'myactions->read') ||
490 $this->user->hasRight('agenda', 'allactions->read');
491 break;
492
493 case 'contract':
494 $permitted = $this->user->hasRight('contrat', 'lire') ||
495 ($view === 'create' && $this->user->hasRight('contrat', 'creer'));
496 break;
497
498 case 'fichinter':
499 $permitted = $this->user->hasRight('ficheinter', 'lire') ||
500 ($view === 'create' && $this->user->hasRight('ficheinter', 'creer'));
501 break;
502
503 case 'adherent':
504 $permitted = $this->user->hasRight('adherent', 'lire') ||
505 ($view === 'create' && $this->user->hasRight('adherent', 'creer'));
506 break;
507
508 case 'categories':
509 $permitted = $this->user->hasRight('categorie', 'lire') ||
510 ($view === 'create' && $this->user->hasRight('categorie', 'creer'));
511 break;
512
513 case 'website':
514 $permitted = isModEnabled('website') && $this->user->hasRight('website', 'read') &&
515 ($view !== 'create' || $this->user->hasRight('website', 'write'));
516 break;
517
518 default:
519 // If we don't have specific permission checks, default to read access
520 $permitted = true;
521 break;
522 }
523
524 // If accessing a specific record, check if user has access to that specific record
525 if ($permitted && $id > 0) {
526 $permitted = $this->checkSpecificRecordAccess($elementType, $id);
527 }
528
529 return $permitted;
530 }
531
539 private function checkSpecificRecordAccess($elementType, $id)
540 {
541 global $db, $conf;
542
543 // For thirdparties, check if user has access to this specific thirdparty
544 if ($elementType === 'thirdparty') {
545 require_once DOL_DOCUMENT_ROOT . '/societe/class/societe.class.php';
546 $soc = new Societe($db);
547 if ($soc->fetch($id) > 0) {
548 return $soc->isInEEC() || $soc->isCustomer() || $soc->isSupplier();
549 }
550 return false;
551 }
552
553 // For projects, check if user is assigned to the project
554 if ($elementType === 'project') {
555 require_once DOL_DOCUMENT_ROOT . '/projet/class/project.class.php';
556 $project = new Project($db);
557 if ($project->fetch($id) > 0) {
558 return $project->restrictedProjectArea($this->user) == 0;
559 }
560 return false;
561 }
562
563 // For other element types, we'll assume access if the user has general permission
564 // In a full implementation, you would check each object type specifically
565 return true;
566 }
567
577 private function generateDescription($type, $view, $id, $statusFilter = '')
578 {
579 global $langs;
580
581 // Load translations
582 $langs->load("companies");
583 $langs->load("bills");
584 $langs->load("orders");
585 $langs->load("propal");
586 $langs->load("projects");
587
588 // Get the label for the element type
589 $label = '';
590 switch ($type) {
591 case 'thirdparty':
592 $label = $langs->trans("ThirdParty");
593 break;
594 case 'contact':
595 $label = $langs->trans("Contact");
596 break;
597 case 'product':
598 $label = $langs->trans("ProductService");
599 break;
600 case 'project':
601 $label = $langs->trans("Project");
602 break;
603 case 'project_task':
604 $label = $langs->trans("Task");
605 break;
606 case 'invoice_customer':
607 $label = $langs->trans("CustomerInvoice");
608 break;
609 case 'invoice_supplier':
610 $label = $langs->trans("SupplierInvoice");
611 break;
612 case 'order':
613 $label = $langs->trans("CustomerOrder");
614 break;
615 case 'order_supplier':
616 $label = $langs->trans("SupplierOrder");
617 break;
618 case 'proposal':
619 $label = $langs->trans("Proposal");
620 break;
621 case 'expedition':
622 $label = $langs->trans("Shipment");
623 break;
624 case 'payment':
625 $label = $langs->trans("Payment");
626 break;
627 case 'payment_supplier':
628 $label = $langs->trans("SupplierPayment");
629 break;
630 case 'bank':
631 $label = $langs->trans("BankAccount");
632 break;
633 case 'agenda':
634 $label = $langs->trans("Event");
635 break;
636 case 'contract':
637 $label = $langs->trans("Contract");
638 break;
639 case 'fichinter':
640 $label = $langs->trans("Intervention");
641 break;
642 case 'adherent':
643 $label = $langs->trans("Member");
644 break;
645 case 'categories':
646 $label = $langs->trans("Category");
647 break;
648 case 'website':
649 $label = $langs->trans("WebSite");
650 break;
651 default:
652 $label = ucfirst($type);
653 break;
654 }
655
656 // Generate description based on view and status
657 if ($view === 'list') {
658 $baseDesc = $langs->trans("ListOf") . " " . $label;
659 if (!empty($statusFilter)) {
660 return $baseDesc . " (" . ucfirst($statusFilter) . ")";
661 }
662 return $baseDesc;
663 } elseif ($view === 'create') {
664 return $langs->trans("New") . " " . $label;
665 } elseif ($id > 0) {
666 return $label . " #" . $id;
667 } else {
668 return $label;
669 }
670 }
671}
$id
Support class for third parties, contacts, members, users or resources.
Definition account.php:47
Abstract base class for all MCP (Model Context Protocol) tools.
Class to manage projects.
Class to manage third parties objects (customers, suppliers, prospects...)
AI tool for generating navigation URLs in Dolibarr.
resolvePath($input, $view)
Maps user-friendly names to specific Dolibarr paths.
getDefinitions()
Returns an array of tool definitions, including name, description, and input schema.
checkPermissions($elementType, $view, $id=0)
Check if user has permissions for the requested resource using the modern hasRight() method.
generateDescription($type, $view, $id, $statusFilter='')
Generate a human-readable description for the URL.
getRequiredRights(string $toolName)
This class already checks the rights of every page it can navigate to.
checkSpecificRecordAccess($elementType, $id)
Check if user has access to a specific record.
execute(string $name, array $args)
Executes the requested tool function based on its name.
getCategories()
Return categories this tool belongs to.
mapStatusToFilter($elementType, $statusFilter)
Maps human-readable status terms to Dolibarr URL parameters for a given element type.
dol_buildpath($path, $type=0, $returnemptyifnotfound=0)
Return path of url or filesystem.
isModEnabled($module)
Is Dolibarr module enabled.
$conf db user
Active Directory does not allow anonymous connections.
Definition repair.php:166