OpenSpec Change: enterprise-api-plugin-procurement

Change ID: enterprise-api-plugin-procurement
Package: @suaveplan/api-plugin-procurement
Category: api/logistics
Target path: api/logistics/api-plugin-procurement
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-procurement.md

Summary

Deliver @suaveplan/api-plugin-procurement on the genesis branch from scratch at enterprise quality. Procurement plugin: supplier management, purchase requisitions (PR), purchase orders (PO) with line items and approval workflow, goods-receipt note (GRN) creation on delivery, three-way matching (PO/GRN/invoice), and supplier performance tracking. Emits procurement:grn:completed on the bus so @suaveplan/api-plugin-inventory can auto-create stock movements. Routes under /procurement. Per-table SurrealQL. Events: procurement:po:created, procurement:po:approved, procurement:grn:completed, procurement:invoice:matched.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`, approval roles
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB
`@suaveplan/events` (`workspace:^`)	Event bus
`@suaveplan/error` (`workspace:^`)	`ProcurementError` hierarchy
`@suaveplan/idempotency` (`workspace:^`)	Mutation guard
`@suaveplan/audit-logging` (`workspace:^`)	Approval audit
`@suaveplan/rate-limiter` (`workspace:^`)	Rate limits
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createProcurementPlugin(config?: ProcurementConfig): PluginDescriptor
// Services: SupplierService, RequisitionService, PurchaseOrderService,
//           GrnService, MatchingService, PerformanceService
// Routes: /procurement/suppliers, /procurement/requisitions, /procurement/purchase-orders,
//         /procurement/grns, /procurement/matching

Error codes

type ProcurementErrorCode =
  | "PROCUREMENT_SUPPLIER_NOT_FOUND"
  | "PROCUREMENT_PO_NOT_FOUND"
  | "PROCUREMENT_PO_ALREADY_APPROVED"
  | "PROCUREMENT_GRN_NOT_FOUND"
  | "PROCUREMENT_MATCH_DISCREPANCY"
  | "PROCUREMENT_APPROVAL_UNAUTHORIZED"

File layout

api/logistics/api-plugin-procurement/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (supplier, requisition, purchase_order, po_line_item, grn, grn_line_item, invoice_match tables)
  src/
    index.ts  events.ts  types/  errors/
    services/supplier/  services/requisition/  services/purchase-order/
    services/grn/  services/matching/  services/performance/
    routes/procurement/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/events, @suaveplan/idempotency, @suaveplan/audit-logging.

3.0 KiB Raw Blame History