81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# OpenSpec Change: enterprise-api-plugin-port-tracking
|
|
|
|
- **Change ID**: enterprise-api-plugin-port-tracking
|
|
- **Package**: `@suaveplan/api-plugin-port-tracking`
|
|
- **Category**: api/logistics
|
|
- **Target path**: `api/logistics/api-plugin-port-tracking`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-port-tracking.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-port-tracking` on the genesis branch from scratch at enterprise quality. Maritime port and vessel tracking plugin: vessel position (AIS data ingestion via pluggable `AisAdapter`), port arrival/departure tracking, berth scheduling, cargo manifest management, estimated-time-of-arrival (ETA) calculations, and integration with `@suaveplan/api-plugin-logistics` for sea-freight shipment correlation. Routes under `/port-tracking`. Per-table SurrealQL. Events: `port:vessel:arrived`, `port:vessel:departed`, `port:ais:update`.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
|
|
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
|
|
| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth` |
|
|
| `@suaveplan/api-plugin-database` (`workspace:^`) | SurrealDB |
|
|
| `@suaveplan/api-plugin-logistics` (`workspace:^`) | Shipment correlation |
|
|
| `@suaveplan/datetime` (`workspace:^`) | ETA calculations |
|
|
| `@suaveplan/events` (`workspace:^`) | Event bus |
|
|
| `@suaveplan/error` (`workspace:^`) | `PortTrackingError` hierarchy |
|
|
| `hono` + `@hono/zod-openapi` + `zod` | Routes |
|
|
| `@opentelemetry/api` | OTel |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
function createPortTrackingPlugin(aisAdapter?: AisAdapter, config?: PortTrackingConfig): PluginDescriptor
|
|
|
|
interface AisAdapter {
|
|
getVesselPosition(mmsi: string): Promise<VesselPosition>
|
|
subscribePositionUpdates(mmsi: string, callback: (pos: VesselPosition) => void): () => void
|
|
}
|
|
|
|
// Routes: GET /port-tracking/vessels/:mmsi, GET /port-tracking/ports/:portCode,
|
|
// GET /port-tracking/ports/:portCode/arrivals, GET /port-tracking/manifests/:id
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type PortTrackingErrorCode =
|
|
| "PORT_VESSEL_NOT_FOUND"
|
|
| "PORT_AIS_UNAVAILABLE"
|
|
| "PORT_CODE_NOT_FOUND"
|
|
| "PORT_BERTH_CONFLICT"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
api/logistics/api-plugin-port-tracking/
|
|
package.json tsconfig.json vitest.config.ts
|
|
surql/ (vessel, port, berth, arrival, cargo_manifest tables)
|
|
src/
|
|
index.ts events.ts types/ errors/
|
|
adapters/ais.port.ts
|
|
services/vessel/ services/port/ services/berth/ services/manifest/ services/eta/
|
|
routes/port-tracking/
|
|
tests/integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/api-plugin-logistics`, `@suaveplan/datetime`.
|