82 lines
3.2 KiB
Markdown
82 lines
3.2 KiB
Markdown
# OpenSpec Change: enterprise-api-plugin-logistics
|
|
|
|
- **Change ID**: enterprise-api-plugin-logistics
|
|
- **Package**: `@suaveplan/api-plugin-logistics`
|
|
- **Category**: api/logistics
|
|
- **Target path**: `api/logistics/api-plugin-logistics`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-logistics.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-logistics` on the genesis branch from scratch at enterprise quality. Shipment-lifecycle plugin: shipments (create/list/detail with carrier fetch/update), carriers (CRUD), pallets, containers, transport legs, and loss-investigation workflows (all missing from the main-branch stub). Per-table SurrealQL. Auth/tenant isolation. Idempotency on mutations. Audit on status changes. Typed events: `logistics:shipment:created|dispatched|delivered|lost`. Carrier label printing hooks for `@suaveplan/barcode`. Integration with `@suaveplan/api-plugin-customs` for cross-border shipments and `@suaveplan/api-plugin-warehouse-ops` for auto-shipment creation.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
|
|
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
|
|
| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth`, permissions |
|
|
| `@suaveplan/api-plugin-database` (`workspace:^`) | SurrealDB |
|
|
| `@suaveplan/events` (`workspace:^`) | Event bus |
|
|
| `@suaveplan/error` (`workspace:^`) | `LogisticsError` hierarchy |
|
|
| `@suaveplan/idempotency` (`workspace:^`) | Mutation guard |
|
|
| `@suaveplan/audit-logging` (`workspace:^`) | Status change audit |
|
|
| `@suaveplan/barcode` (`workspace:^`) | Label printing |
|
|
| `@suaveplan/rate-limiter` (`workspace:^`) | Rate limits |
|
|
| `hono` + `@hono/zod-openapi` + `zod` | Routes |
|
|
| `@opentelemetry/api` | OTel |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
function createLogisticsPlugin(config?: LogisticsConfig): PluginDescriptor<LogisticsConfig>
|
|
// Services: ShipmentService, CarrierService, PalletService, ContainerService,
|
|
// TransportLegService, LossInvestigationService
|
|
// Routes: /logistics/shipments, /carriers, /pallets, /containers,
|
|
// /transport-legs, /loss-reports
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type LogisticsErrorCode =
|
|
| "LOGISTICS_SHIPMENT_NOT_FOUND"
|
|
| "LOGISTICS_CARRIER_NOT_FOUND"
|
|
| "LOGISTICS_ILLEGAL_STATUS_TRANSITION"
|
|
| "LOGISTICS_PALLET_OVERLOAD"
|
|
| "LOGISTICS_CONTAINER_FULL"
|
|
| "LOGISTICS_LOSS_REPORT_NOT_FOUND"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
api/logistics/api-plugin-logistics/
|
|
package.json tsconfig.json vitest.config.ts
|
|
surql/ (carrier, shipment, pallet, container, transport_leg, loss_report tables)
|
|
src/
|
|
index.ts events.ts types/ errors/
|
|
services/shipment/ services/carrier/ services/pallet/
|
|
services/container/ services/transport-leg/ services/loss-investigation/
|
|
routes/shipments/ routes/carriers/ routes/pallets/
|
|
routes/containers/ routes/transport-legs/ routes/loss-reports/
|
|
tests/integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/events`, `@suaveplan/idempotency`, `@suaveplan/audit-logging`, `@suaveplan/barcode`.
|