# 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`.