Três camadas de extensão
Config declarativa, código extensível e core LTS — sem fork por cliente.
| Camada | Quem edita | Upgrade |
|---|---|---|
| Config (manifest, features, workflows) | Mirá + cliente (YAML) | Git + deploy |
| Plugins Go | Mirá / backend custom | semver plugin + compatibleCore |
| Apps UX substituíveis | Mirá, parceiro ou cliente | npm pin + deploy front |
| Core LTS | Mirá platform | Pin LTS no manifest |
Contrato de compatibilidade
O core pode evoluir sem quebrar plugins pinados. Breaking só com major do protocolo + notificação.
| Mudança no core | Plugin existente | Quem age |
|---|---|---|
| Aditiva (hook novo, campo opcional, refactor interno) | Continua no pin actual | Ninguém obrigatório |
| Patch CVE na mesma linha LTS | Continua | Cliente só se bumpa o pin da imagem |
| Breaking (hook removido, deny code, campo obrigatório) | Fora do range após CoreLine major | Autor do plugin no upgrade; cliente opt-in |
Plugin declara compatibleCore (ex. ^0.2.0) contra commerceext.CoreLine. Breaking sobe 0.2 → 1.0, nunca 0.3. Notificação: Release do commerce-ext + issues nos templates. Detalhe: docs/extensibility-model.md · ADR 0048.
Estado de implementação
Atualize esta tabela no repo ao entregar cada componente.
| Componente | Documentado | Código | Notas |
|---|---|---|---|
| OpenAPI contrato | Documentado | Protótipo | Fase 2a: handlers Go |
| MCP tools (6) | Documentado | Protótipo | Mock explorer → servidor real |
| Extension Protocol | Documentado | Documentado | commerce-ext/ in-process |
| Extension Host | Documentado | Documentado | internal/ext Bootstrap |
| Hook points (10+) | Documentado | Documentado | 10/10 wired |
| Event bus | Documentado | Protótipo | In-process · outbox Fase 3a |
| Workflow YAML | Documentado | Protótipo | UX protótipo; engine Fase 3a |
| manifest.yaml cliente | Documentado | Planejado | Fase 4 template |
Extension Protocol — regras
Contrato entre core LTS e plugins. Pacote público: commerce-ext (Go). Plugins nunca importam core/internal/*.
| Regra | Motivo |
|---|---|
| Interfaces pequenas e estáveis | Semver previsível |
| Plugin só importa commerce-ext | Isolamento |
| Extensões declaradas em manifest.yaml | CI auditable |
| Negócio no core ou plugin | Nunca metade no front |
| Eventos at-least-once | Handlers idempotentes |
| Falha de plugin não derruba processo | Degradação controlada |
Manifest do plugin (referência)
apiVersion: commerce.mira.dev/v1
kind: Plugin
id: reference-antifraud
version: 1.0.0
compatibleCore: "^0.2.0"
runtime:
type: in-process
binary: extensions/reference-antifraud
capabilities:
hooks:
- checkout.risk_assess
events:
subscribe:
- payment.attempt.failed
- payment.attempt.blockedVerify: go run ./cmd/commerce-ext verify --manifest extensions/reference-antifraud/manifest.yaml
Hook points v1 (síncronos)
Timeout default 300ms · panic capturado → PLUGIN_FAILURE.
| Hook | Momento | Pode bloquear? |
|---|---|---|
| checkout.validate | Antes criar/submeter pedido | Sim |
| checkout.quote_adjust | Ajuste de totais | Sim |
| order.pre_confirm | Antes confirmar | Sim |
| order.pre_cancel | Antes cancelar | Sim |
| payment.route | Rota gateway/split | Sim |
| catalog.price_resolve | Preço final SKU | Sim |
| inventory.allocate | Reserva estoque | Sim |
| member.eligibility | Elegibilidade revendedor | Sim |
| integration.transform_outbound | Payload ERP saída | Transform |
| integration.transform_inbound | Payload ERP entrada | Transform |
Eventos core (assíncronos)
Plugins publicam eventos namespaced, ex.: acme.erp.synced.
| Evento | Quando |
|---|---|
| order.created | Pedido criado |
| order.confirmed | Confirmado |
| order.cancelled | Cancelado |
| payment.authorized | Pagamento autorizado |
| payment.captured | Captura |
| inventory.reserved | Reserva |
| inventory.released | Liberação |
Manifest cliente (repo deploy)
Pin do core LTS e módulos opcionais — Fase 4 template.
core:
image: mira-commerce-core:1.2.4 # pin LTS — nunca :latest em prod
modules:
member_network: true
marketplace_split: true
conversational: true
plugins:
- id: acme-erp-adapter
version: 1.0.0
vertical:
preset: generic-b2cVerify CI (Fase 2b): commerce-ext verify --manifest manifest.yaml
Checklist — nova extensão
- Hook/evento listado em ARCHITECTURE ou ADR novo
- Contrato em OpenAPI ou commerce-ext IDL (se exposto a integradores)
- Timeout, idempotência e falha degradada documentados
- Schema Postgres ext_<plugin> se persistência (ADR 0004)
- Exemplo no plugin referência ou mock do protótipo
- Atualizar estado de implementação em extensibility-model.md
Anti-patterns
| Evitar | Preferir |
|---|---|
| Fork core por cliente | Pin LTS + plugins |
| Regra de negócio só no React | API + hook |
| Plugin importa internal/ | Só commerce-ext |
| SQL direto em core.* | CoreReader / CoreWriter |
| :latest em produção | Pin no manifest |
| Breaking silencioso no protocolo | ADR + CoreLine major + issues nos templates |
| Forçar upgrade porque o main avançou | Pin LTS; migrate opt-in |