78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# OpenSpec Change: enterprise-api-plugin-gtap
|
|
|
|
- **Change ID**: enterprise-api-plugin-gtap
|
|
- **Package**: `@suaveplan/api-plugin-gtap`
|
|
- **Category**: api/logistics
|
|
- **Target path**: `api/logistics/api-plugin-gtap`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-gtap.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-gtap` on the genesis branch from scratch at enterprise quality. Global Trade Automation Platform (GTAP) integration bridge: import/export license management, tariff classification (HS code + origin), sanctioned-party screening (OFAC/EU/UN lists via pluggable `SanctionScreenAdapter`), certificate-of-origin generation, preferential-trade-agreement (PTA) eligibility checking, and AEO (Authorised Economic Operator) status tracking. Routes under `/gtap`. Per-table SurrealQL. Events: `gtap:sanction:hit`, `gtap:certificate:issued`, `gtap:license:expired`.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
|
|
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
|
|
| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth`, `requireRole` |
|
|
| `@suaveplan/api-plugin-database` (`workspace:^`) | SurrealDB |
|
|
| `@suaveplan/api-plugin-customs` (`workspace:^`) | HS code reference |
|
|
| `@suaveplan/audit-logging` (`workspace:^`) | Sanction hit + license audit |
|
|
| `@suaveplan/events` (`workspace:^`) | Event bus |
|
|
| `@suaveplan/error` (`workspace:^`) | `GtapError` hierarchy |
|
|
| `hono` + `@hono/zod-openapi` + `zod` | Routes |
|
|
| `@opentelemetry/api` | OTel |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
function createGtapPlugin(config?: GtapConfig): PluginDescriptor
|
|
interface SanctionScreenAdapter { screen(entity: ScreenRequest): Promise<ScreenResult> }
|
|
// Routes: /gtap/licenses, /gtap/screen, /gtap/certificates,
|
|
// /gtap/pta-eligibility, /gtap/aeo-status
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type GtapErrorCode =
|
|
| "GTAP_LICENSE_NOT_FOUND"
|
|
| "GTAP_LICENSE_EXPIRED"
|
|
| "GTAP_SANCTION_HIT"
|
|
| "GTAP_CERTIFICATE_NOT_FOUND"
|
|
| "GTAP_PTA_NOT_ELIGIBLE"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
api/logistics/api-plugin-gtap/
|
|
package.json tsconfig.json vitest.config.ts
|
|
surql/ (trade_license, sanction_screening_log, certificate_of_origin, aeo_status tables)
|
|
src/
|
|
index.ts events.ts types/ errors/
|
|
adapters/sanction-screen.port.ts
|
|
services/license/ services/screening/ services/certificate/
|
|
services/pta/ services/aeo/
|
|
routes/gtap/
|
|
tests/integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/api-plugin-customs`, `@suaveplan/audit-logging`.
|