T

Stéphane Tailland b0fa4a1aa2 Add the OpenAPI spec for the sales domain

The developer portal listed this API with no reference documentation:
catalog was the only domain that had a spec anywhere in the tree.

Generated from the backend's own drf-spectacular schema
(/classic-models/api/schema/, version 4.7.0), filtered to the operations
this domain's gateway actually exposes — derived from the Kong routes and
their request-transformer rewrites in Konnect, not from guesswork. Every
route resolved to a backend operation; the counts match one for one.

Paths and server are the **gateway's**, not the backend's. A portal
reader calls https://sales-dev.sttlab.local/sales/v1/..., and the
gateway rewrites that onto /classic-models/api/v1/... upstream. Path
parameters are renamed to the gateway's capture names where the backend
used a different case.

Components are pruned to what these paths transitively reference.

Note: catalog-api/openapi.yaml does NOT follow this convention — it
documents the backend paths and http://localhost:8000 as its server, so
its operations cannot be called as written from the portal. Left alone
here; worth aligning separately.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-26 18:28:25 +02:00

dev

Point the control-plane ref at the stable mirror CR

2026-08-26 16:30:15 +02:00

kong

Build sales-api REST + MCP layers (Layer 3), full build in one pass

2026-08-23 17:02:17 +02:00

openapi.yaml

Add the OpenAPI spec for the sales domain

2026-08-26 18:28:25 +02:00

README.md

Build sales-api REST + MCP layers (Layer 3), full build in one pass

2026-08-23 17:02:17 +02:00

README.md

sales-api

Kong routing/policy layer for the sales slice of classic-models-api (see /Users/stephanetailland/git/classic-models-api), split out per the DDD decomposition in ../kong-konnect-deployment-strategy.md. The backend stays a single monolith — only Kong does the domain split. Structure mirrors ../payments-api/../customers-api — single MCP route, not ../catalog-api's original two-route pattern (see ../STATUS.md section 18).

Two resources, both with a REST surface and MCP tools:

Order (single key ordernumber) — full CRUD + an order-details sub-resource (GET /sales/v1/orders/{ordernumber}/order-details/, mirrors the backend's own @action on OrderViewSet).
Orderdetail (composite key ordernumber + productcode, exposed as its own top-level resource — the backend does this too, not just nested under Order).

Route	Method	Backend path
`/sales/v1/orders/`	GET, POST	`/classic-models/api/v1/orders/`
`/sales/v1/orders/{ordernumber}/`	GET, PUT, PATCH, DELETE	`/classic-models/api/v1/orders/{ordernumber}/`
`/sales/v1/orders/{ordernumber}/order-details/`	GET	`/classic-models/api/v1/orders/{ordernumber}/order-details/`
`/sales/v1/orderdetails/`	GET, POST	`/classic-models/api/v1/orderdetails/`
`/sales/v1/orderdetails/{ordernumber}/{productcode}/`	GET, PUT, PATCH, DELETE	`/classic-models/api/v1/orderdetails/{ordernumber}/{productcode}/`
`/sales-mcp`	GET, POST, DELETE	MCP streamable-http (tools call into the REST routes above)

Auth & MCP tool ACLs

openid-connect on both surfaces (sales-api REST audience, mcp-sales MCP audience), RFC 8693 exchange chain MCP → sales-api → classic-models-api, same shape as every other domain. IdP: local Keycloak (https://keycloak.sttlab.local/realms/classic-models).

MCP write-tool ACLs (create-order, create-orderdetail) are admin + customer + support — deliberately different from customers-api's/ payments-api's admin-only write tools, because it's what the real backend permission classes actually allow, verified directly against authentication/permissions.py rather than assumed by analogy: OrderPermission.check()/OrderScopedPermission.check() give support an unconditional pass at the class-level (has_permission) check — the "status-only" restriction usually associated with support is enforced at the object level (has_object_permission), which only applies to existing records (update/delete), not create. read_only/ product_manager are excluded (both classes only pass those roles for SAFE_METHODS).

Correction to note: payments-api's create-payment tool (built earlier this session) restricted writes to admin only, described at the time as "verified against PaymentPermission's actual logic" — but PaymentPermission extends this same OrderScopedPermission base class, so by the same reasoning above, customer and support should also have been included there. Not fixed as part of this domain's build (out of scope, and it's more restrictive than the backend rather than less, so not a safety issue) — flagged here and in ../STATUS.md for whoever revisits payments-api's MCP tool ACLs.

Structure

Same dev/ + kong/rest/ + kong/mcp/ layout as payments-api. Deploy key and broker secret follow the same reused/mirrored pattern (catalog-api's deploy key, broker's real secret pulled live from Keycloak and copied to kong-v2/sales-api/* in Vault).