98 lines
5.1 KiB
Markdown
98 lines
5.1 KiB
Markdown
# Helper Endpoint Contracts
|
|
|
|
This spec covers helper, lookup, search, and stats endpoints that support forms and dashboards. The main business save/delete/status endpoints are covered in the WMS, Accounting, Master Data, System Settings, and Document Lifecycle specs.
|
|
|
|
## Common Contract
|
|
|
|
Unless a route explicitly differs, helper endpoints:
|
|
|
|
- Load authenticated context through `db_auth.php`.
|
|
- Scope reads by the active `company_id`.
|
|
- Return JSON.
|
|
- Are consumed by AJAX from PHP pages.
|
|
- Should not mutate business documents unless their name says `manage`, `remove`, `delete`, `approve`, `confirm`, `cancel`, `void`, `issue`, `post`, `receive`, or `update`.
|
|
|
|
## ICS Search And Lookup
|
|
|
|
| Endpoint | Purpose | Main consumers |
|
|
|---|---|---|
|
|
| `app/ics/api/engine/contact_search.php` | Search contacts for stock/document forms. | Stock in/out/transfer and document source forms. |
|
|
| `app/ics/api/engine/product_search.php` | Search active products/SKUs for stock forms. | Stock in/out/transfer forms. |
|
|
| `app/ics/api/engine/barcode_lookup.php` | Resolve scanned barcode into product, lot/serial, or location context. | Scanner workflows and barcode-enabled forms. |
|
|
| `app/ics/api/engine/validate_scan_location.php` | Validate scanned warehouse/zone/aisle/rack context. | Scanner workflows. |
|
|
| `app/ics/api/engine/retrieve_stock_by_source.php` | Return stock rows linked to a source document. | WMS document detail and approval/deletion context. |
|
|
|
|
## ICS Location Helpers
|
|
|
|
| Endpoint | Purpose |
|
|
|---|---|
|
|
| `app/ics/api/engine/retrieve_warehouse.php` | Return active warehouses available to the company. |
|
|
| `app/ics/api/engine/retrieve_zone.php` | Return zones for a warehouse. |
|
|
| `app/ics/api/engine/retrieve_aisle.php` | Return aisles for a warehouse/zone. |
|
|
| `app/ics/api/engine/retrieve_rack.php` | Return racks for a warehouse/zone/aisle. |
|
|
|
|
These endpoints are driven by warehouse/storage setup and company location mode. They are used to populate dependent dropdowns and validate manual location selection.
|
|
|
|
## ICS Lot And Serial Helpers
|
|
|
|
| Endpoint | Purpose |
|
|
|---|---|
|
|
| `app/ics/api/engine/retrieve_lot.php` | Return known lots for a product/SKU. |
|
|
| `app/ics/api/engine/retrieve_active_lot.php` | Return lots with active stock availability. |
|
|
| `app/ics/api/engine/retrieve_active_serial.php` | Return serial numbers with active stock availability. |
|
|
| `app/ics/api/engine/sku_label_lots.php` | Return lots available for SKU label generation. |
|
|
| `app/ics/api/engine/sku_label_products.php` | Return products available for SKU label generation. |
|
|
|
|
## Stats Endpoints
|
|
|
|
| Endpoint | Purpose |
|
|
|---|---|
|
|
| `app/accounting/api/engine/account_stats.php` | Chart of accounts summary cards/statistics. |
|
|
| `app/accounting/api/engine/department_stats.php` | Department summary cards/statistics. |
|
|
| `app/contact/api/engine/contact_stats.php` | Contact summary cards/statistics. |
|
|
| `app/inventory/api/engine/product_stats.php` | Product summary cards/statistics. |
|
|
| `app/inventory/api/engine/warehouse_stats.php` | Warehouse summary cards/statistics. |
|
|
| `app/ics/api/engine_report/product_stats.php` | Stock/product operational statistics. |
|
|
| `app/ics/api/engine_report/warehouse_stats.php` | Stock overview warehouse statistics. |
|
|
| `app/dashboard/api/engine_report/reports_stats.php` | WMS dashboard cards and charts; gated by transaction limits. |
|
|
|
|
Stats endpoints are read-only dashboard/list-page support routes. They should follow the same quota behavior as their parent dashboard/report area where `UsageGuard` is applied.
|
|
|
|
## Retrieve Endpoints
|
|
|
|
Retrieve endpoints return one record or a bounded list needed by an edit form.
|
|
|
|
| Module | Endpoints |
|
|
|---|---|
|
|
| Contact | `retrieve_contact.php`, `retrieve_contact_type.php` |
|
|
| Inventory | `retrieve_category.php`, `retrieve_product.php`, `retrieve_storage.php`, `retrieve_warehouse.php` |
|
|
| Stock | `retrieve_stock_in.php`, `retrieve_stock_out.php`, `retrieve_stock_transfer.php` |
|
|
| Order | `retrieve_order.php`, `retrieve_invoice.php`, `retrieve_return.php` |
|
|
| PO | `retrieve_po.php`, `retrieve_supplier_return.php` |
|
|
| Revenue | `retrieve_quotation.php` |
|
|
| Expense | `retrieve_purchase_request.php` |
|
|
| Accounting | `retrieve_account.php`, `retrieve_department.php`, `get_journal_detail.php` |
|
|
| Settings | `retrieve_company.php`, `retrieve_profile.php`, `retrieve_smtp.php`, `retrieve_users.php` |
|
|
|
|
Expected behavior:
|
|
|
|
- Validate active company scope.
|
|
- Return only active positive-company rows unless the feature explicitly needs historical/deleted records.
|
|
- Avoid exposing rows from another company even when an ID is guessed.
|
|
|
|
## Generic Inventory Manager Endpoint
|
|
|
|
Endpoint: `app/inventory/api/engine/manager.php`
|
|
|
|
This route is an inventory utility endpoint guarded to owner/admin roles. It belongs with product/category/warehouse/storage maintenance and should not be used for unauthenticated or cross-module access.
|
|
|
|
## Endpoint Documentation Rule
|
|
|
|
When adding a new helper endpoint, update this file if the endpoint is not already clearly covered by a feature spec. Include:
|
|
|
|
- Endpoint path.
|
|
- Read/write behavior.
|
|
- Main consumer page.
|
|
- Important company/role/limit guards.
|
|
- Payload shape when frontend code depends on exact fields.
|