LinkedOrderSettlement Mesa Comandas

LinkedOrderSettlement — Mesa com múltiplas comandas

Documentação técnica do contrato mesa → comandas (tabs) → carts/sales no settlement de pedidos vinculados, coberta pelo smoke E2E do flowchart 1 (garçom + mesas + comandas) em app-community#605.

Visão e escopo

Item	Valor
Issue	app-community#605
Programa pai	app-community#601 (flowchart admin id=1 — Venda / produção)
Módulo principal	ui-orders
Telas / contrato	LinkedOrderSettlementPage, árvore via useLinkedOrderSettlementTree + helpers
Visões (APP_TYPE)	POS (PDV), modo operacional waiter (garçom), check-order-type=table
Flowchart admin	id=1 (flowKey=sales-production)
Catálogo smoke	fluxo: pedido-criacao, flowchartIds: [1]

O que o módulo faz neste fluxo

No PDV em modo garçom com gestão por mesa:

1. Abre (ou seleciona) uma mesa (orderType: table) como raiz da árvore.
2. Abre uma ou mais comandas (orderType: tab) sob a mesma mesa (mainOrderId aponta para a mesa).
3. Lança itens em carts ligados a cada comanda; ao avançar no fluxo de produção, surgem sales com status operacional (ex.: Ready).
4. No settlement, lista todas as comandas descendentes da mesa — a segunda comanda não remove nem oculta a primeira.

O que o módulo não deve fazer neste fluxo

• Não fecha cobrança / pagamento POS ou CHECKOUT nesta etapa (escopo das filhas #606 / #607).
• Não substitui o catálogo canônico de fluxos de smoke nem os flowcharts do admin.
• Não altera authZ/backend: a listagem de tabs é filtragem em memória sobre a árvore já carregada.

Modelo da árvore (regras de negócio)

table (raiz, externalCode = código da mesa)
├── tab A (comanda)
│   ├── cart A (itens em aberto)
│   └── sale A (após produção / Ready, quando aplicável)
└── tab B (comanda)
    ├── cart B
    └── sale B

• mainOrderId (ou equivalente normalizado) liga filho → pai.
• orderType normalizado: table | tab | cart | sale.
• Settlement da mesa agrega todas as tabs sob a raiz; critério de aceite do smoke: duas comandas visíveis no settlement da mesma mesa.

Helpers canônicos

Arquivo: src/react/pages/checkout/linkedOrderSettlementHelpers.js

Função	Papel
collectOrderDescendants(rootOrderId, orders)	Percorre a árvore a partir da raiz e devolve todos os descendentes (com __treeDepth).
listLinkedTabsUnderRoot(rootOrderId, orders)	Filtra descendentes com orderType === 'tab'. Garante que a 2ª comanda não apaga a 1ª.

Testes unitários de referência: src/tests/react/pages/checkout/linkedOrderSettlementHelpers.test.js (casos #605: duas tabs sob a mesma mesa; primeira tab permanece após lançar a segunda).

Hooks/páginas relacionados (contrato existente, reutilizado):

• useLinkedOrderSettlementTree.js / useLinkedOrderSettlement.js
• LinkedOrderSettlementPage.js
• linkedOrderSettlementTreeOps.js
• utilitários linkedOrderContext (normalizeLinkedOrderType, etc.)

Smoke E2E (contrato de evidência)

Suite Playwright no módulo:

Artefato	Caminho
Spec	src/tests/browser/pos/flowchart1WaiterTabs.spec.js
Fixtures	src/tests/browser/pos/flowchart1WaiterTabs.fixtures.js
Mock API / sessão	src/tests/browser/pos/flowchart1WaiterTabs.mock.js
Screenshots	src/tests/browser/pos/screenshots/flowchart-1-waiter-tabs/

Metadados obrigatórios no smoke:

• fluxo: pedido-criacao
• flowchartIds: [1]

Prints previstos por etapa (nomes de referência):

1. 01-mesa
2. 02-comanda-a
3. 03-comanda-b
4. 04-itens
5. 05-settlement-duas-comandas
6. 06-ready

Config de device usada no mock do smoke (resumo): pos-operation-mode: waiter, check-order-type: table, check-order-management-mode: manage, cobrança local desligada (fora de escopo desta issue).

Gate QA: evidência visual completa (prints por etapa + manifesto) é obrigatória para agent:qa:accepted. Ver Smoke Test Flows e skill canônica em agents-mcp.

Fluxo resumido

flowchart TD
  A[PDV garçom / device table] --> B[Abrir ou selecionar mesa]
  B --> C[Abrir comanda A]
  C --> D[Lançar itens na comanda A]
  D --> E[Abrir comanda B na mesma mesa]
  E --> F[Lançar itens na comanda B]
  F --> G[Settlement da mesa]
  G --> H{listLinkedTabsUnderRoot}
  H --> I[Comanda A e B visíveis]
  I --> J[PCP / sales Ready]
  J --> K[Fora de escopo: cobrança]

Loading

Visões (APP_TYPE)

Visão	Papel neste fluxo
POS	Dono do fluxo operacional: mesa, comandas, lançamento de itens, settlement e handoff para produção.
PPC	Consome sales/status para fila de produção / Ready (não implementado nesta issue; só observado no smoke até Ready).
MANAGER / ADMIN	Configuração de device (modo waiter, check-order-type table) e publicação do flowchart id=1 — não executam a jornada de mesa no PDV.
CRM / SHOP	Fora deste ramo do flowchart 1.

Referência de fronteiras: MODOS_OPERACAO.md.

Modularização e qualidade

• Arquivos da entrega #605 mantidos ≤ 500 linhas (code-quality.md).
• Reuso do contrato LinkedOrderSettlement já existente; extensão pontual do helper de listagem de tabs.
• Branch de referência: ui-orders task-605 → dev (3ce22ba / merge 2da8be7).

Links relacionados

Destino	URL
Issue #605	https://github.com/ControleOnline/app-community/issues/605
Programa #601	https://github.com/ControleOnline/app-community/issues/601
Flowchart admin 1	https://admin.controleonline.com/admin/flowcharts/1
Smoke Test Flows (app)	https://github.com/ControleOnline/app-community/wiki/Smoke-Test-Flows
Skill smoke-test-flows	https://github.com/ControleOnline/agents-mcp/blob/master/agents/skills/shared/quality/smoke-test-flows.md
Home ui-orders	https://github.com/ControleOnline/ui-orders/wiki
App-Home	https://github.com/ControleOnline/app-community/wiki

Fora de escopo desta página

• Implementação de fechamento/cobrança multi-comanda (filhas do programa #601).
• Inventário completo de todos os smokes do flowchart 1.
• Alteração do catálogo canônico de fluxos sem solicitação humana.