Sistema de Ordem de Serviço do zero

Objetivo

Criar a conta, o projeto Assistec Manutenção Exemplo e conhecer o Mad Studio, para que as 30 aulas seguintes tenham onde acontecer.

O que você terá no fim

• Conta ativa no manager, com login funcionando.
• Projeto Assistec Manutenção Exemplo criado e aberto no Mad Studio.
• Interface em português e no tema claro.
• Noção do que cada grupo do rail faz e em qual aula do curso ele é usado.
• Dois caminhos para abrir qualquer painel: o rail e a busca rápida (Ctrl+P).
• Clareza sobre o que será construído nas 30 aulas seguintes.

Manager › Meus projetos

Manager › Meus projetos › Novo projeto

Studio › Início

Studio › Rail expandido

Passo a passo

1. Abra manager.madbuilder.dev. A tela Entrar na sua conta aparece.
2. Se ainda não tem conta: clique em Criar conta grátis, preencha Nome, E-mail e Senha e confirme o e-mail que chega na caixa de entrada.
3. Preencha E-mail e Senha, marque Manter-me conectado por 30 dias e clique em Entrar.
4. Se a conta tiver verificação em duas etapas, digite o Código de seis dígitos do aplicativo autenticador e confirme.
5. Você cai em Meus projetos. Clique no card Criar projeto (o primeiro da lista; a barra lateral também tem o link Novo projeto).
6. Fique na aba Em branco. As outras duas abas — Templates e Gerar com IA — não são usadas neste curso.
7. Em Nome do projeto, digite Assistec Manutenção Exemplo.
8. Ícone e Logo são opcionais (PNG ou JPG, até 4 MB). Pode deixar em branco — dá para definir depois em Propriedades do projeto.
9. Clique em Criar projeto e aguarde. A criação monta a estrutura inicial do projeto e leva alguns segundos.
10. No card do projeto, clique em Abrir — ele leva ao detalhe do projeto. É lá (e na visão em lista) que fica o Abrir Mad Studio. Clique nele: o editor abre com o rail à esquerda e a área central vazia.
11. No rail, clique em Expandir menu para ver os nomes dos painéis. O botão vira Recolher menu.
12. Reconheça o grupo Principal, o do dia a dia: Arquivos (as telas e os códigos do projeto), Buscar, Documentação (os guias escritos), Modelos de dados (o desenho do banco — aulas 02 e 03), Banco de dados (o console SQL — aula 27), Importar 4.0 e Transformers (aula 23).
13. Desça para Geração & ferramentas. É o grupo mais cheio, e quase todo o curso passa por ele: Gerar CRUDs em lote (aula 04), Rotas da API e MCP Server (aula 26), Editor de menus (aula 05), MadTrace · observabilidade (aula 27), Agendador · schedule.php (aula 23), Fluxos de Aprovação (aula 22), Tenancy & Banco (aula 25), Acesso de Agente (MCP) (aula 26) e Teste online (o sistema rodando de verdade — aula 06).
14. Em seguida vem Módulos & acesso: Módulos, Grupos de permissão e Perfis de acesso. Os três são a aula 05 inteira.
15. O rail rola: a seta Mais itens abaixo indica que há mais coisa. Continue até Customização — Traduções e Temas (aula 24) e Arquivos customizados (aula 26).
16. Por último, o grupo Deploy: Servidores de deploy, Deploy SSH, Git Deploy, Hospedagem · MadCloud e Pacotes Composer. É o módulo 7 do curso, nas aulas 28 e 29. Abaixo dele, já fora de qualquer grupo, fica o bloco fixo do rodapé: Baixar projeto (aula 29), Estatísticas e atividades, Compartilhar projeto (as duas na aula 30) e Propriedades do projeto (aula 25).
17. No rail global (a borda mais externa), reconheça Projetos, Loja, Ajuda, Novidades, Reportar bug e Conta.
18. Abra Conta e confira que o tema está em Tema claro. Se estiver escuro, clique em Tema claro.
19. Ainda em Conta, note que é dali que saem Minha conta, Preferências e Sair. O painel volta na aula 30.
20. Pressione Ctrl+P (ou ⌘P no Mac) para abrir Ir para / Buscar. O campo diz "Buscar arquivos, telas, modelos, ações…" — ou seja, a busca cobre as quatro coisas.
21. Digite modelos e pressione Enter. O painel Modelos de dados abre.
22. Feche a aba pelo X e reabra pelo rail, para confirmar que os dois caminhos levam ao mesmo lugar.
23. Abra o painel Documentação (grupo Principal) e localize o card deste curso. É a versão escrita de tudo o que você vai ver em vídeo, com os mesmos prints.
24. Deixe o Studio aberto — a aula 02 continua exatamente daqui.

Erros comuns

Checklist de encerramento

• Consigo entrar no manager com e-mail e senha.
• O projeto Assistec Manutenção Exemplo aparece em Meus projetos.
• Abrir Mad Studio carrega o editor sem erro.
• O rail expandido mostra os cinco grupos (Principal, Geração & ferramentas, Módulos & acesso, Customização e Deploy) — os dois últimos só depois de rolar a lista.
• Sei dizer em qual grupo ficam Modelos de dados, Gerar CRUDs em lote e Teste online.
• Encontrei o card do curso em Documentação.
• Anotei a lista de dados fictícios que o curso usa do começo ao fim.
• Ctrl+P abre a busca e encontra Modelos de dados.
• A interface está em português e no tema claro.
• Sei abrir o mesmo painel de duas formas: pelo rail e pela busca rápida.

Aula 02 — Primeiras tabelas à mão →

Objetivo

Desenhar à mão as três primeiras tabelas do sistema — cliente, especialidade e tecnico — para você entender coluna por coluna o que o MadBuilder faz com cada tipo, cada flag e cada relacionamento.

O que você terá no fim

• Um modelo de dados chamado Ordem de Serviço no projeto.
• Três tabelas desenhadas: cliente (18 colunas), especialidade (8) e tecnico (16).
• Colunas padrão (created_at, updated_at, deleted_at) nascendo sozinhas em toda tabela nova.
• Uma coluna descritiva por tabela — o texto que aparece no lugar do id em toda ligação (e a marca automática da plataforma desfeita onde ela errou o alvo).
• Uma ligação 1:n entre tecnico e especialidade, criada pela toolbar.
• A coluna gerente_id com IDX (índice), pronta para o organograma da aula 19.
• Clareza sobre por que a plataforma ainda não cria chave estrangeira de uma tabela para ela mesma.

Studio › Modelos de dados › Novo modelo de dados

Studio › Modelos de dados › Ordem de Serviço

Studio › Modelos de dados › Ordem de Serviço › cliente

Studio › Modelos de dados › Ordem de Serviço › Nova foreign key

Studio › Modelos de dados › Ordem de Serviço › tecnico › gerente_id

Studio › Modelos de dados › Ordem de Serviço

Passo a passo

1. No rail, abra Modelos de dados.
2. Clique em Criar modelo de dados (se o projeto já tiver algum modelo, o botão é Novo modelo).
3. No modal Novo modelo de dados, preencha:
   • Nome: Ordem de Serviço
   • Database name: assistec
   • Tipo de banco: deixe no padrão (PostgreSQL)
4. Clique em Criar modelo. A área de desenho abre com a mensagem Diagrama vazio e o botão Adicionar tabela no meio — enquanto o modelo não tem nenhuma tabela, não existe canvas para clicar.
5. Na toolbar, clique em Propriedades do diagrama (o primeiro botão, ícone de engrenagem).
6. Em Colunas padrões ao criar tabela, use Adicionar coluna padrão três vezes e preencha a grade (Nome, Tipo, Tamanho, Valor padrão, Rótulo, Not null, Esconder):

   Nome	Tipo	Not null
   created_at	Timestamp (Timestamp)	Não
   updated_at	Timestamp (Timestamp)	Não
   deleted_at	Timestamp (Timestamp)	Não

7. Em Colunas de inserção automáticas, aponte Horário de criação do registro para created_at, Horário de atualização do registro para updated_at e Horário de deleção do registro para deleted_at. É o que faz o sistema gerado preencher essas datas sozinho.
8. Clique em Salvar. A regra vale para as tabelas criadas a partir de agora.
9. Crie a tabela cliente. Com o modelo vazio, o caminho é o botão Adicionar tabela da tela Diagrama vazio: ele abre o modal Nova entidade, onde você escolhe o tipo (Tabela, já selecionado), digita cliente em Nome e clica em Criar.
   Da segunda tabela em diante o caminho é outro, e é o que o vídeo mostra: clique no botão Nova tabela da toolbar (o + com o ícone de banco) e depois no canvas, no ponto onde ela deve nascer. Enquanto o modo está armado, uma faixa no topo avisa Clique no canvas onde a TABELA deve aparecer (e Cancelar desarma). A tabela nasce com o nome já em edição: digite por cima e tecle Enter. Se você clicar fora antes de digitar, ela fica como tabela_1 — aí sim use o duplo clique no título (Duplo clique para renomear).
10. Passe o mouse sobre o card de cliente: os botões de ação aparecem em volta dele. Clique em Adicionar coluna (o +). A coluna nasce e o editor Editar coluna abre sozinho, com o nome selecionado. Preencha Nome, Tipo, Tamanho (quando o tipo pedir), Valor padrão e os selos de marcação; não existe botão Salvar — o editor grava quando você o fecha (Esc, o X ou um clique fora). Os selos são:

    selo	o que é
    NN	Not null — campo obrigatório
    UQ	Único — não aceita valor repetido
    AI	Auto-increment (só na chave primária)
    UUID	chave primária em UUID (só na chave primária)
    Desc	Descritiva — o texto que aparece no lugar do id nas ligações
    IDX	Índice — busca mais rápida por esta coluna

    Cadastre a lista abaixo:

    Coluna	Tipo (na UI)	Tamanho	NN	Valor padrão	Outros selos
    tipo_pessoa	Char (Caractere fixo)	2	não	PJ	—
    nome_razao_social	Varchar (Texto curto)	200	sim	—	Desc
    cpf_cnpj	Varchar (Texto curto)	20	não	—	—
    email	Varchar (Texto curto)	150	não	—	—
    telefone	Varchar (Texto curto)	30	não	—	—
    cep	Varchar (Texto curto)	10	não	—	—
    logradouro	Varchar (Texto curto)	200	não	—	—
    numero	Varchar (Texto curto)	20	não	—	—
    complemento	Varchar (Texto curto)	100	não	—	—
    bairro	Varchar (Texto curto)	100	não	—	—
    cidade	Varchar (Texto curto)	100	não	—	—
    uf	Char (Caractere fixo)	2	não	—	—
    observacoes	Text (Texto longo)	—	não	—	—
    ativo	Boolean (Booleano)	—	sim	true	—

11. Confira a coluna descritiva antes de seguir. Quando a tabela ainda não tem nenhuma coluna marcada como Desc, a plataforma marca uma sozinha — e em cliente isso acontece na primeira coluna que você digita, tipo_pessoa. Marcar nome_razao_social depois não desmarca a primeira: as duas ficam com o olho azul. Abra tipo_pessoa e desmarque Desc.
12. O card nasce com 220 × 180 e rola por dentro: com 18 colunas você só vê as primeiras. Clique no card e arraste a alça do canto inferior direito até ver a tabela inteira.
13. Crie a segunda tabela pelo caminho da toolbar (Nova tabela → clique no canvas → digite o nome → Enter) e chame de especialidade:

    Coluna	Tipo (na UI)	Tamanho	NN	Valor padrão	Outros selos
    nome	Varchar (Texto curto)	100	sim	—	UQ, Desc
    descricao	Text (Texto longo)	—	não	—	—
    cor	Varchar (Texto curto)	20	não	—	—
    ativo	Boolean (Booleano)	—	sim	true	—

14. Crie a terceira tabela, tecnico, do mesmo jeito:

    Coluna	Tipo (na UI)	Tamanho	NN	Valor padrão	Outros selos
    nome	Varchar (Texto curto)	150	sim	—	Desc
    matricula	Varchar (Texto curto)	30	não	—	UQ
    cargo	Varchar (Texto curto)	60	não	—	—
    foto	Varchar (Texto curto)	500	não	—	—
    email	Varchar (Texto curto)	150	não	—	—
    telefone	Varchar (Texto curto)	30	não	—	—
    custo_hora	Double (Decimal)	—	não	0	—
    valor_hora_cliente	Double (Decimal)	—	não	0	—
    capacidade_hora_dia	Double (Decimal)	—	não	8	—
    ativo	Boolean (Booleano)	—	sim	true	—

15. Ligue tecnico a especialidade: na toolbar, clique no botão 1:n, depois clique no card tecnico (a origem) e por último no card especialidade (o destino). A plataforma cria sozinha a coluna especialidade_id em tecnico, nomeia a chave fk_tecnico_1 e desenha a linha entre os dois cards.
16. Crie a coluna gerente_id em tecnico com tipo Int (Inteiro), sem NN. É essa coluna que o organograma da aula 19 usa como pai.
17. Agora veja por que ela é um inteiro comum e não uma chave: no card tecnico, abra a seção Foreign keys e clique no +. No modal Nova foreign key, a origem já vem travada em tecnico; escolha Coluna FK = gerente_id e Tabela alvo = tecnico. Ao clicar em Criar FK a mensagem é literal: "Origem e destino devem ser tabelas diferentes (auto-FK não suportado nesta versão)." Clique em Cancelar.
    Pela ferramenta 1:n da toolbar o aviso não aparece: clicar duas vezes na mesma tabela simplesmente cancela o modo, sem mensagem nenhuma. Quem explica o motivo é o modal.
18. Volte na coluna gerente_id (duplo clique na linha) e marque o selo IDX. Diferente dos outros selos, ele grava na hora — o índice é outro registro, não um campo da coluna.
19. Confira o card tecnico: 16 colunas (id, as três datas, as dez que você digitou, especialidade_id e gerente_id). O rodapé do card mostra FK 1 e IDX 1.
20. Confirme no canto direito da toolbar o texto Salvo agora. O diagrama grava a cada alteração — não existe botão Salvar.
21. Use Ajustar à tela para enquadrar as três tabelas e deixe o canvas pronto para o print de fechamento.

Erros comuns

Checklist de encerramento

• O modelo Ordem de Serviço aparece em Modelos de dados.
• O canvas mostra as três tabelas: cliente, especialidade e tecnico.
• Toda tabela tem id, created_at, updated_at e deleted_at.
• cliente tem 18 colunas e só nome_razao_social está marcada como Desc (confira que tipo_pessoa ficou sem a marca).
• especialidade.nome está NN, UQ e Desc.
• tecnico.matricula está UQ e tecnico.nome está Desc.
• tecnico tem 16 colunas e o rodapé do card mostra FK 1 e IDX 1.
• Existe a linha 1:n entre tecnico e especialidade, com a coluna especialidade_id.
• tecnico.gerente_id existe, é Int (Inteiro) e está com IDX marcado.
• A toolbar mostra Salvo agora (nenhuma alteração pendente).
• Sei explicar, em uma frase, para que serve a coluna descritiva.

← Aula 01 — Conta, projeto e tour do Studio · Aula 03 — Completar o modelo (Importar schema SQL) →

Objetivo

Trazer as outras onze tabelas do sistema de uma vez com o Importar schema SQL, cadastrar os status da ordem de serviço, configurar dados fake para o Teste Online e marcar um checkpoint do modelo.

O que você terá no fim

• 14 tabelas no modelo Ordem de Serviço (186 colunas), com os relacionamentos desenhados.
• As três tabelas da aula 02 preservadas — elas aparecem como Já existe — pulada.
• Os seis status da OS cadastrados como dados fixos em status_os.
• Seeds de dev configurados para as tabelas principais.
• Um checkpoint manual chamado modelo completo.
• O id de todas as tabelas com numeração automática (AI) — o importador lê o SERIAL do script e já marca.
• Noção do que o importador lê do script e do que ele ignora.

Studio › Modelos de dados › Importar Schema SQL

Studio › Modelos de dados › Importar Schema SQL

Studio › Modelos de dados › Importar Schema SQL

Studio › Modelos de dados › Ordem de Serviço

Studio › Modelos de dados › status_os › Inserir dados de teste

Studio › Modelos de dados › Seeds de dev (Faker)

Studio › Modelos de dados › Checkpoints do modelo de dados

O script da aula

Cole exatamente este conteúdo (ele também está em sql/a03-importar.sql). As três primeiras tabelas estão ali de propósito, para você ver o comportamento de "já existe":

-- Aula 03 — cole este script em Modelos de dados → Importar schema SQL → Colar SQL.
-- Só CREATE TABLE com REFERENCES inline (é o que o importador lê).
-- cliente, especialidade e tecnico já existem (aula 02): aparecem como "já existe" e são puladas.

CREATE TABLE cliente (
  id SERIAL PRIMARY KEY,
  nome_razao_social VARCHAR(200) NOT NULL
);

CREATE TABLE especialidade (
  id SERIAL PRIMARY KEY,
  nome VARCHAR(100) NOT NULL
);

CREATE TABLE tecnico (
  id SERIAL PRIMARY KEY,
  nome VARCHAR(150) NOT NULL
);

CREATE TABLE status_os (
  id      SERIAL PRIMARY KEY,
  codigo  VARCHAR(30) NOT NULL UNIQUE,
  nome    VARCHAR(60) NOT NULL,
  cor     VARCHAR(20),
  ordem   INTEGER DEFAULT 0,
  e_final BOOLEAN DEFAULT false
);

CREATE TABLE tecnico_especialidade (
  id               SERIAL PRIMARY KEY,
  tecnico_id       INTEGER NOT NULL REFERENCES tecnico(id),
  especialidade_id INTEGER NOT NULL REFERENCES especialidade(id),
  nivel            VARCHAR(20),
  dt_certificacao  DATE
);

CREATE TABLE equipamento (
  id                    SERIAL PRIMARY KEY,
  cliente_id            INTEGER NOT NULL REFERENCES cliente(id),
  codigo_patrimonio     VARCHAR(50),
  nome                  VARCHAR(200) NOT NULL,
  tipo                  VARCHAR(100),
  marca                 VARCHAR(100),
  modelo                VARCHAR(100),
  numero_serie          VARCHAR(100),
  dt_aquisicao          DATE,
  dt_garantia_fim       DATE,
  localizacao_descricao VARCHAR(250),
  ativo                 BOOLEAN DEFAULT true
);

CREATE TABLE servico (
  id                   SERIAL PRIMARY KEY,
  codigo               VARCHAR(30) UNIQUE,
  nome                 VARCHAR(200) NOT NULL,
  descricao            TEXT,
  especialidade_id     INTEGER REFERENCES especialidade(id),
  preco                NUMERIC(12,2) DEFAULT 0,
  duracao_estimada_min INTEGER,
  ativo                BOOLEAN DEFAULT true
);

CREATE TABLE peca (
  id             SERIAL PRIMARY KEY,
  sku            VARCHAR(50) UNIQUE,
  ean            VARCHAR(20),
  nome           VARCHAR(200) NOT NULL,
  descricao      TEXT,
  unidade_medida VARCHAR(10) DEFAULT 'un',
  preco_custo    NUMERIC(12,2) DEFAULT 0,
  preco_venda    NUMERIC(12,2) DEFAULT 0,
  estoque_atual  NUMERIC(12,3) DEFAULT 0,
  estoque_minimo NUMERIC(12,3) DEFAULT 0,
  ativo          BOOLEAN DEFAULT true
);

CREATE TABLE ordem_servico (
  id                 SERIAL PRIMARY KEY,
  numero             VARCHAR(30) NOT NULL UNIQUE,
  titulo             VARCHAR(150) NOT NULL,
  cliente_id         INTEGER NOT NULL REFERENCES cliente(id),
  equipamento_id     INTEGER REFERENCES equipamento(id),
  tecnico_id         INTEGER REFERENCES tecnico(id),
  status_os_id       INTEGER NOT NULL REFERENCES status_os(id),
  tipo               VARCHAR(30) DEFAULT 'corretiva',
  prioridade         VARCHAR(20) DEFAULT 'media',
  descricao_problema TEXT NOT NULL,
  descricao_solucao  TEXT,
  dt_abertura        TIMESTAMP NOT NULL,
  dt_agendada        TIMESTAMP,
  dt_prevista        TIMESTAMP,
  dt_inicio          DATE,
  dt_fim             DATE,
  progresso          INTEGER DEFAULT 0,
  os_pai_id          INTEGER,                 -- OS pai (hierarquia do Gantt); auto-FK não é suportada no modelo, fica como inteiro
  dt_conclusao       TIMESTAMP,
  horas_trabalhadas  NUMERIC(10,2) DEFAULT 0,
  valor_servicos     NUMERIC(12,2) DEFAULT 0,
  valor_pecas        NUMERIC(12,2) DEFAULT 0,
  valor_deslocamento NUMERIC(12,2) DEFAULT 0,
  valor_total        NUMERIC(12,2) DEFAULT 0,
  status_aprovacao   VARCHAR(20) DEFAULT 'rascunho',
  observacoes        TEXT,
  created_at         TIMESTAMP,
  updated_at         TIMESTAMP,
  deleted_at         TIMESTAMP
);

CREATE TABLE os_servico_item (
  id               SERIAL PRIMARY KEY,
  ordem_servico_id INTEGER NOT NULL REFERENCES ordem_servico(id),
  servico_id       INTEGER NOT NULL REFERENCES servico(id),
  quantidade       NUMERIC(10,2) DEFAULT 1,
  preco_unitario   NUMERIC(12,2) DEFAULT 0,
  desconto_pct     NUMERIC(5,2)  DEFAULT 0,
  subtotal         NUMERIC(12,2) DEFAULT 0,
  observacao       VARCHAR(250)
);

CREATE TABLE os_peca_item (
  id               SERIAL PRIMARY KEY,
  ordem_servico_id INTEGER NOT NULL REFERENCES ordem_servico(id),
  peca_id          INTEGER NOT NULL REFERENCES peca(id),
  quantidade       NUMERIC(10,3) NOT NULL DEFAULT 1,
  preco_unitario   NUMERIC(12,2) DEFAULT 0,
  subtotal         NUMERIC(12,2) DEFAULT 0,
  numero_serie     VARCHAR(100)
);

CREATE TABLE os_anexo (
  id                SERIAL PRIMARY KEY,
  ordem_servico_id  INTEGER NOT NULL REFERENCES ordem_servico(id),
  tipo              VARCHAR(20),
  nome_arquivo      VARCHAR(200),
  arquivo           VARCHAR(500),
  imagem            VARCHAR(500),
  assinatura_base64 TEXT,
  nome_signatario   VARCHAR(150),
  codigo_lido       VARCHAR(100),
  descricao         VARCHAR(250),
  created_at        TIMESTAMP
);

CREATE TABLE os_historico (
  id               BIGSERIAL PRIMARY KEY,
  ordem_servico_id INTEGER NOT NULL REFERENCES ordem_servico(id),
  titulo           VARCHAR(120) NOT NULL,
  observacao       TEXT,
  dt_evento        TIMESTAMP NOT NULL,
  icone            VARCHAR(40),
  cor              VARCHAR(20),
  status_anterior  VARCHAR(60),
  status_novo      VARCHAR(60),
  usuario_nome     VARCHAR(120)
);

CREATE TABLE os_apontamento (
  id                  BIGSERIAL PRIMARY KEY,
  ordem_servico_id    INTEGER NOT NULL REFERENCES ordem_servico(id),
  tecnico_id          INTEGER NOT NULL REFERENCES tecnico(id),
  dt_referencia       DATE NOT NULL,
  tipo                VARCHAR(20) DEFAULT 'execucao',
  horas               NUMERIC(6,2) NOT NULL DEFAULT 0,
  valor_hora          NUMERIC(12,2) DEFAULT 0,
  descricao_atividade VARCHAR(250)
);

Baixar a03-importar.sql

Passo a passo

1. Abra Modelos de dados e entre no modelo Ordem de Serviço.
2. Na toolbar, clique em Importar schema SQL. Abre o modal Importar Schema SQL.
3. Em Banco de dados, escolha PostgreSQL. Esse campo é o dialeto do script que você vai colar (MySQL / MariaDB, PostgreSQL, SQLite, Oracle, SQL Server, Firebird), não o banco do projeto — ele muda como o importador lê tipos como character varying e TINYINT(1).
4. Em Origem, deixe Colar SQL selecionado. A outra opção, Upload arquivo, aceita .sql ou .txt.
5. Cole o script inteiro na área de texto.
6. Clique em Analisar. Nada é criado ainda — é leitura.
7. Confira a linha de totais: 14 tabela(s) · 121 coluna(s) · 16 FK(s).
8. Leia o bloco Antes de importar — o que este dump não traz. Ele lista o que o script não resolve e o que você vai precisar ajustar depois. Com este script aparece um aviso:
   • ℹ️ 28 coluna(s) NOT NULL sem DEFAULT — o formulário gerado vai exigir o preenchimento. Se o dado antigo não tem valor, ajuste a coluna ou defina um padrão.

   O que não aparece também informa: não há aviso de chave primária sem sequence, porque o importador lê o SERIAL/BIGSERIAL do script e já marca o selo AI na chave primária.

   Se você usa uma versão anterior da plataformae vir o aviso ⚠️ *N tabela(s) com chave primária inteira SEM sequence*, o id das tabelas importadas entrou como inteiro comum: abra o id de cada uma com duplo clique, marque o selo AI e feche com Esc. Sem isso, o CRUD da aula 04 pede o número do registro em toda gravação.
9. O bloco Criar N relação(ões) sugerida(s) pelos nomes das colunas não aparece com este script: ele só existe quando o dump não traz nenhuma relação declarada, e o nosso declara todas com REFERENCES. Se um dia aparecer, deixe-o desmarcado até conferir cada palpite.
10. Na lista de pré-visualização, confirme que cliente, especialidade e tecnico estão marcadas como Já existe — pulada, e que as outras onze estão como Pronta para importar.
11. Clique em Importar 11 tabela(s) e aguarde. O resultado mostra os totais Tabelas, Colunas e FKs criados, a lista Puladas (3) (cliente, especialidade e tecnico — *já existe no diagrama*) e a mensagem Importação concluída sem erros. Clique em Fechar.
12. As tabelas novas entram empilhadas a partir do centro da tela, muitas vezes por cima das que já existiam. Arraste os cards para organizar (o diagrama grava a posição sozinho) e use Ajustar à tela na toolbar para ver o modelo inteiro. Com tudo à vista, repare no card ordem_servico: o os_pai_id é um inteiro comum, sem linha de ligação — é a mesma limitação de auto-relacionamento da aula 02, e o Gantt da aula 18 trabalha com a coluna.
13. Confira uma das importadas: dê um duplo clique na linha id de equipamento. O selo AI já está marcado — veio do SERIAL. Feche com Esc.
    Atalho para achar cada tabela: use a lista da esquerda (Buscar tabela…) e o botão Ver … no diagrama, que centraliza o card no canvas.
14. Opcional, só para conhecer: o botão Template de tabelas traz modelos pré-prontos (CRUDs, kanban, calendário, gantt). Não usamos no curso porque queremos o modelo do zero.
15. Cadastre os status da OS. Passe o mouse sobre o card status_os (ou clique nele): os botões de ação aparecem em volta do card. Clique no de Inserir dados de teste. Na aba Dados fixos, use Adicionar linha e preencha:

    id	codigo	nome	cor	ordem	e_final
    1	ABERTA	Aberta	#8b96ad	1	false
    2	AGENDADA	Agendada	#1E55E8	2	false
    3	EM_ATENDIMENTO	Em atendimento	#F26B1F	3	false
    4	AGUARDANDO_PECA	Aguardando peça	#d98e00	4	false
    5	CONCLUIDA	Concluída	#3DA86F	5	true
    6	CANCELADA	Cancelada	#D93A2B	6	true

    O id é obrigatório: a grade exige valor em toda coluna Not null, e a chave primária é uma delas. Se deixar em branco, o Salvar não fecha e aparece *Todos os campos de "id" são obrigatórios.* As colunas created_at, updated_at e deleted_at também estão na grade (elas vieram das colunas padrão do modelo) e podem ficar vazias.

16. A última coluna da grade (StatusOs::CONST) é opcional: o nome que você digitar ali vira uma constante no código gerado. Deixe em branco se não for usar.
17. Clique em Salvar.
18. Na toolbar, clique em Seeds de dev (Faker). Abre o assistente Seeds de dev (Faker) — configuração em lote.
19. No Passo 1 de 2, marque as tabelas que devem receber dados fake: cliente, tecnico, equipamento, servico, peca, ordem_servico, os_servico_item, os_peca_item, os_historico e os_apontamento. Cada tabela marcada já mostra o campo Registros ali mesmo (sugestão: 20 para cliente e equipamento, 8 para tecnico, 40 para ordem_servico, 10 para as demais). Clique em Avançar.
20. No Passo 2 de 2, confira a coluna Provider Faker de cada coluna (e ajuste os Registros, se preferir). O provider Auto (inferido) já acerta a maioria: nome, e-mail, telefone, CNPJ, cidade, preço. A chave primária aparece como ID sequencial (auto) e as FKs como FK → tabela (sorteia do alvo).
21. Clique em Salvar tudo. Os dados não são gerados agora: eles nascem no Teste Online, quando você clicar em Popular dados de teste (aula 06) — é o que diz o rodapé do assistente.
22. Na toolbar, clique em Checkpoints do modelo. Abre o painel Checkpoints do modelo de dados.
23. Clique em Criar checkpoint manual, preencha Nome do checkpoint com modelo completo e clique em Salvar. Ele passa a aparecer na lista como v1, com a marca MANUAL e o resumo 14 tab · 186 col.
24. Selecione o checkpoint na lista e veja a área de comparação (De / Até) e o Preview da migration. Logo depois de criado, comparado com Estado atual do modelo, o painel mostra 0 mudança — é assim que você compara o modelo de hoje com o de qualquer marco. Se você mexer em algo depois, a diferença aparece ali: no print da aula, os dados fixos de status_os gravados depois do checkpoint aparecem em Dados de seed alterados (informativo — seeds não re-rodam em instalações existentes).
25. Ainda na toolbar, abra Migrations do projeto para ver a tela Migrations & seeds do projeto — a lista dos arquivos que a próxima publicação vai emitir (migrations/ com o *create tables* e o *add foreign keys*, seeders/ProjectDevSeeder.php e os .sql de inserts). É só pré-visualização; nada é gravado. Feche.

Erros comuns

Checklist de encerramento

• O canvas mostra 14 tabelas (186 colunas no total).
• O id das 11 tabelas importadas já veio com AI marcado (conferi em pelo menos uma).
• cliente, especialidade e tecnico continuam com as colunas da aula 02 (não foram sobrescritas).
• ordem_servico tem as ligações para cliente, equipamento, tecnico e status_os (o os_pai_id fica como inteiro, sem ligação).
• status_os tem as seis linhas de status, com id de 1 a 6, cor e ordem.
• Os seeds de dev estão salvos para pelo menos cliente, tecnico, equipamento e ordem_servico.
• O checkpoint manual modelo completo aparece na lista.
• Abri Migrations do projeto e vi a lista de arquivos da próxima publicação.
• A toolbar mostra Salvo agora.

← Aula 02 — Primeiras tabelas à mão · Aula 04 — Gerar CRUDs em lote →

Objetivo

Transformar as tabelas do modelo em telas de verdade — formulário e listagem por tabela, mais um formulário mestre-detalhe para a ordem de serviço — numa única execução.

O que você terá no fim

• Formulário e listagem gerados para cliente, especialidade, tecnico, servico, peca, equipamento e status_os.
• Um formulário mestre-detalhe de ordem_servico com serviços, peças e anexos.
• Os módulos Cadastros e Operação criados direto no gerador, com as telas já distribuídas entre eles.
• Entendimento do que o chip JÁ EXISTE protege.
• Noção do que dá para mudar depois (tudo) e do que é melhor decidir agora (o módulo).

Studio › Geração de CRUDs em lote

Studio › Geração de CRUDs em lote

Studio › Geração de CRUDs em lote › Personalizar — OrdemServico

Studio › Geração de CRUDs em lote

Studio › Geração de CRUDs em lote

Passo a passo

1. No rail, abra Gerar CRUDs em lote. A aba Geração de CRUDs em lote ocupa a tela em três colunas (o gerador não é um modal: é uma aba do workspace, e o botão Gerar fica no topo).
2. Na coluna esquerda, Padrões para todas, configure:
   • Layout do formulário: Duas colunas
   • Apresentação do formulário: Página inteira
   • Tipo de listagem: Listagem com busca no cabeçalho
   • Mensagem após salvar: Toast
3. Em Módulo padrão, clique no + à direita do combo (dica: Novo módulo). O combo vira um campo com o texto de apoio Nome do novo módulo: digite Cadastros e confirme no botão ✓ (dica: Criar módulo). O módulo é criado na hora e já fica selecionado.
4. Na coluna do meio, confira o nome do banco (base: assistec) e use o campo Filtrar tabelas… se precisar. A lista vem em ordem alfabética, não na ordem do diagrama.
5. Marque estas sete tabelas:

   Tabela	O que vira
   cliente	formulário + listagem
   equipamento	formulário + listagem
   especialidade	formulário + listagem
   peca	formulário + listagem
   servico	formulário + listagem
   status_os	formulário + listagem
   tecnico	formulário + listagem

   O contador no topo da lista passa a mostrar 7 / 14 selecionadas. Cada card marcado abre quatro pílulas de ajuste rápido — Módulo, Nomes, Rótulos e Rota — já preenchidas a partir dos padrões (Módulo: Cadastros, Nomes: ClienteForm, ClienteList, Rótulos: Clientes, Rota: /clientes).

6. Não marque tecnico_especialidade, os_servico_item, os_peca_item, os_anexo, os_historico nem os_apontamento. Elas são tabelas filhas: aparecem dentro de outras telas.
7. Marque também ordem_servico e clique na engrenagem do card (dica: Personalizar). Abre o modal Personalizar — OrdemServico: o título usa o nome amigável da tabela e o nome físico (ordem_servico) fica no subtítulo.
8. Desça até a seção Master-detail. O subtítulo diz 5 tabela(s) detalhe detectada(s) via FK.
9. Marque Gerar como Master-Detail e ajuste a lista:

   Tabela detalhe	FK	Marcar?	Estilo
   os_servico_item	ordem_servico_id	sim	FieldList
   os_peca_item	ordem_servico_id	sim	FieldList
   os_anexo	ordem_servico_id	sim	DetailForm
   os_historico	ordem_servico_id	não	—
   os_apontamento	ordem_servico_id	não	—

   Cada linha nasce desmarcada e com DetailForm aceso; as pílulas só ficam clicáveis depois de marcar a linha.

10. Ainda no modal, na seção Módulo / Submódulo / Sub-submódulo (subtítulo Padrão: Cadastros), crie e escolha o módulo Operação pelo +, do mesmo jeito do passo 3. Submódulo e Sub-submódulo ficam desabilitados enquanto o módulo não tiver filhos (— sem submódulos — / — n/a —). Feche em OK.
11. Confira a coluna direita, Resumo da geração: 8 Tabelas, 16 Páginas, 32 Arquivos (.php + .blade.php), a lista Arquivos a gerar agrupada por módulo e a estimativa (~9s para gerar · Você pode editar tudo depois).
12. Clique em Gerar 8 CRUDs, no topo. A faixa mostra Gerando X/8… com a porcentagem e o botão de cancelar vira Cancelar execução enquanto roda.
13. No fim aparece a faixa Concluído: 8 criados, 0 já existiam, 0 falharam. A seleção é zerada no sucesso; se algo falhar ou você cancelar, ela é preservada e a faixa avisa *Seleção mantida — clique em Gerar para tentar de novo*.
14. Abra Arquivos no rail e confirme as 16 telas geradas: ClienteForm e ClienteList, EquipamentoForm/EquipamentoList, EspecialidadeForm/EspecialidadeList, PecaForm/PecaList, ServicoForm/ServicoList, StatusOsForm/StatusOsList, TecnicoForm/TecnicoList e OrdemServicoForm/OrdemServicoList.
15. Abra uma delas com um duplo clique só para ver o editor visual. Não mexa em nada ainda — a edição começa na aula 07.

Erros comuns

Checklist de encerramento

• O módulo Cadastros existe e é o Módulo padrão do gerador.
• O módulo Operação existe e é o módulo de ordem_servico.
• Em Arquivos aparecem formulário e listagem das sete tabelas de cadastro (14 telas).
• Existe OrdemServicoForm gerado como mestre-detalhe e OrdemServicoList.
• O formulário da OS tem serviços e peças como FieldList e anexos como DetailForm.
• Nenhuma tela foi gerada para os_historico, os_apontamento ou tecnico_especialidade.
• A faixa de conclusão mostrou 8 criados, 0 já existiam, 0 falharam.
• Sei dizer o que o chip JÁ EXISTE protege.

← Aula 03 — Completar o modelo (Importar schema SQL) · Aula 05 — Módulos, menu, grupos e perfis →

Objetivo

Organizar as telas geradas em módulos, arrumar o menu que o usuário vai ver e definir quem enxerga o quê, com grupos de permissão e perfis de acesso.

O que você terá no fim

• Três módulos: Cadastros, Operação e Relatórios, com ícone, cor e posição de menu.
• Dois submódulos dentro de Cadastros (Pessoas e Catálogo).
• O Menu lateral com os grupos na ordem certa e salvo.
• Três grupos de permissão: Atendimento, Técnico e Financeiro.
• Quatro perfis de acesso: Atendente, Técnico, Gerente e Diretoria.
• Entendimento da diferença entre módulo (organização), grupo (pacote de telas) e perfil (quem recebe o pacote).

Studio › Módulos › Módulo: Cadastros

Studio › Editor de menus › Menu lateral

Studio › Grupos de permissão

Studio › Perfis de acesso

Passo a passo

1. No rail, no grupo Módulos & acesso, abra Módulos. Ele abre um painel à esquerda (não é aba): o clique no item do rail é um interruptor — clicar de novo fecha o painel. Os módulos Cadastros e Operação já estão lá, criados pelo gerador na aula 04, sem cor e sem ícone.
2. Clique no + do cabeçalho do painel (dica: Novo módulo (raiz)) e preencha:
   • Tipo: Módulo — *Domínio de negócio (raiz)* (os outros cartões são Submódulo e Sub-submódulo)
   • Nome: Relatórios
   • Código: deixe o valor sugerido (relato, curto e em snake_case)
   • O bloco Caminho: mostra app/Modules/Relatórios enquanto você digita
   • Posição do menu: Lateral esquerdo (as outras são Superior e Dropdown)
   • Controller / Método: deixe vazios (só para módulo que abre uma tela ao ser clicado)
   • Aparência: escolha uma cor da paleta e clique em Escolher ícone — o seletor busca entre os ícones Lucide pelo nome (ex.: FileText)
   • Descrição (opcional): Relatórios operacionais e financeiros
3. Clique em Criar módulo.
4. Passe o mouse na linha Cadastros da árvore: aparece um + no fim da linha (dica: Adicionar submódulo). Crie Pessoas (para cliente e tecnico) e repita com Catálogo (para servico, peca e equipamento). No modal de submódulo o botão final é Criar submódulo.
5. Clique num módulo: abre a aba Módulo: <nome> no workspace, com Páginas · Tabelas · Submódulos · Última edição no topo, os cards dos submódulos, o bloco Detalhes do módulo (Identificador, Caminho, Permissões, Cor, Ícone, Visível no menu) e a Zona de perigo com Excluir módulo. É aqui, no detalhe, que se ajusta a aparência dos módulos que vieram do gerador: escolha uma Cor na paleta e clique em Escolher no campo Ícone (em módulo que já tem um, o botão é Trocar). Faça isso em Cadastros e em Operação.
6. Abra Editor de menus no rail — ele fica no grupo Geração & ferramentas, não junto dos outros três painéis desta aula. As abas em cima são os quatro menus do sistema: Menu lateral, Menu superior, Menu público e Dropdown da navbar. Fique em Menu lateral. À direita fica o modo: Apenas visual (padrão) ou Edição completa.
7. Cada item tem uma alça de arrasto (⠿) à esquerda. Antes de reordenar, recolha os grupos pelas setinhas: com os grupos abertos você solta o item dentro da lista de filhos sem querer — e isso não é só cosmético (veja o aviso abaixo). Ordem sugerida: Operação, Cadastros, Relatórios.
8. O botão Item (criar item de menu do zero) só existe no modo Edição completa. No modo Apenas visual os itens vêm das telas e dos módulos, e você só reordena, renomeia, troca ícone/cor e exclui.
9. Confira o resultado antes de gravar, na barra do editor: A–Z reordena o menu inteiro em ordem alfabética, Código abre Código gerado (menu.xml) e Diff abre Diferenças do menu (à esquerda o menu atual, à direita o resultado das suas alterações). No modo Apenas visual a barra tem só esses três botões mais o Salvar.
10. Clique em Salvar. O aviso alterações não salvas some e aparece Menu salvo.
11. Abra Grupos de permissão no rail (aqui é aba, não painel) e clique em Novo grupo.
12. Em Identificação, preencha Nome do grupo com Atendimento. O campo Code pode ficar vazio — é gerado automaticamente.
13. Na seção Páginas (contador N de 16), marque as telas — elas aparecem pelo nome do controller, com o selo MAD. Ao marcar, abre embaixo a linha AÇÕES com Visualizar · Incluir · Editar · Excluir · Exportar. Use este desenho:

    Grupo	Telas (controllers)	Ações
    Atendimento	ClienteForm, ClienteList, EquipamentoForm, EquipamentoList, OrdemServicoForm, OrdemServicoList	Visualizar, Incluir, Editar
    Técnico	OrdemServicoForm, OrdemServicoList, TecnicoForm, TecnicoList, EspecialidadeForm, EspecialidadeList	Visualizar, Editar
    Financeiro	OrdemServicoForm, OrdemServicoList, ServicoForm, ServicoList, PecaForm, PecaList	Visualizar, Exportar

14. A seção Códigos lista controllers e classes do projeto. Aqui ela está em 0 de 0 — entra na aula 26, quando existir código customizado.
15. Clique em Salvar grupo (o botão largo no fim do formulário; o Salvar do cabeçalho faz a mesma coisa) e repita os passos 11 a 14 para Técnico e Financeiro.
16. Abra Perfis de acesso no rail e clique em Novo perfil.
17. Em Dados do perfil, o Code é gerado do nome (Diretoria → diretoria) — e é por ele que os Fluxos de Aprovação da aula 22 encontram o aprovador; só preencha à mão se quiser um código diferente do nome. Preencha Nome e Descrição:

    Perfil	Descrição	Grupos marcados
    Atendente	Abre e acompanha ordens de serviço	Atendimento
    Técnico	Executa e atualiza as ordens em campo	Técnico
    Gerente	Acompanha a operação inteira	Atendimento, Técnico, Financeiro
    Diretoria	Aprova orçamentos acima de R$ 5.000	Financeiro

18. Na seção Grupos, marque os grupos do perfil. A lista traz seis: os três que você criou mais um por módulo (Operação, Cadastros, Relatórios), que a plataforma mantém sozinha.
19. A seção Programas extras serve para liberar uma tela solta, com ações próprias, sem precisar criar um grupo só para ela. Deixe vazia por enquanto.
20. Clique em Salvar perfil e repita para os outros três.

Erros comuns

Checklist de encerramento

• Existem os módulos Cadastros, Operação e Relatórios.
• Cadastros tem os submódulos Pessoas e Catálogo.
• Todos os módulos têm ícone, cor e Visível no menu ligado.
• O Menu lateral está na ordem Operação · Cadastros · Relatórios e foi salvo (Menu salvo).
• Ordem de Serviços continua dentro de Operação no menu.
• Existem os grupos Atendimento, Técnico e Financeiro, cada um com telas e ações.
• Existem os perfis Atendente, Técnico, Gerente e Diretoria.
• O perfil Gerente acumula os três grupos.
• Sei explicar a diferença entre módulo, grupo de permissão e perfil.

← Aula 04 — Gerar CRUDs em lote · Aula 06 — Teste Online →

Objetivo

Colocar o sistema no ar num ambiente descartável, entrar nele com usuário e senha e ver, pela primeira vez, as telas, o menu e o banco funcionando de verdade.

O que você terá no fim

• Um ambiente de Teste Online publicado, com URL própria.
• A senha do admin definida por você.
• O banco criado, as tabelas migradas e os seis status já cadastrados.
• O sistema aberto no navegador, com o menu da aula 05.
• Clareza sobre a diferença entre publicar de novo, popular dados e recriar o ambiente.

Studio › Teste online

Studio › Teste online › Credenciais do admin

Studio › Teste online

Aplicação › Início

Aplicação › Cadastros › Clientes

Studio › Teste online › Sync estrutural

Passo a passo

1. No rail, abra Teste online. O painel abre à esquerda do workspace (é painel, não aba — e o clique no rail é interruptor: clicar de novo fecha). Se ainda não houve publicação, o estado é Sem ambiente ativo e a mensagem Nenhum deploy realizado ainda.
2. No card Credenciais do admin, confira o Login (admin) — a Senha já vem sorteada e mascarada. Digite uma senha sua, com no mínimo seis caracteres: o botão Salvar só aparece depois que você mexe no campo. Clique em Salvar.
   • Se o ambiente ainda não existe, a confirmação é Senha salva — vale a partir do próximo publish.
   • Com o ambiente no ar, ela vira Senha aplicada no ambiente ativo.
   • Use uma senha exclusiva deste ambiente de teste. Não reaproveite senha de e-mail ou banco.
   • O olho ao lado do campo revela a senha; o ícone de cópia copia sem revelar.
3. Confira Servidor (PHP 8.4), Banco de dados (SQLite) e Conector (Banco do teste online). Deixe nos valores padrão.
4. Clique em Testar agora. O painel mostra Deploy em andamento e percorre os cinco passos: Preparando metadados → Gerando arquivos → Criando container → Subindo banco → Publicando código.
   • Com SQLite, Subindo banco aparece riscado: não existe servidor de banco separado para subir, o arquivo vive dentro do próprio container.
5. No fim abre o aviso Teste Online publicado 🎉, com a URL e as credenciais do admin em claro. Feche (ou use Abrir aplicação) — não deixe esse aviso na tela se estiver gravando. O topo do painel passa a mostrar ONLINE, a URL ativa, o botão Abrir aplicação e a linha há Nm · PHP 8.4 · SQLite · 18.9s.
6. Clique em Popular dados de teste. Ele gera, no ambiente que está rodando, os registros configurados nos seeds de dev da aula 03. O resultado sai em uma linha, no formato cliente: 19 · especialidade: 10 · tecnico: 8 · ….
   • ⚠️ Semeie primeiro, cadastre depois. O resultado do popular nem sempre convive com os registros que você cadastrou à mão: depois de um Testar agora a contagem já voltou ao número do seed e a massa cadastrada teve de ser refeita. Rode o popular no começo e só então cadastre os dados do curso.
7. Clique em Abrir aplicação. O sistema gerado abre numa aba nova.
8. Entre com o usuário admin e a senha que você definiu no passo 2 (campo Usuário, campo Senha, botão ENTRAR).
9. Confira no sistema:
   • a tira de ícones à esquerda, um ícone por módulo — clicar num deles abre a lista de telas daquele módulo. Relatórios ainda não aparece: módulo sem tela não é desenhado no menu;
   • em Cadastros: Clientes, Especialidades, Tecnicos, Status de Os, Equipamentos, Serviços e Pecas — os rótulos saem automaticamente do nome da tabela, sem acento (ajustáveis pela pílula Rótulos do gerador ou no menu);
   • em Operação: Ordem de Serviços — abra um registro e repare nas grades de serviços e peças que o gerador já montou dentro do formulário;
   • a listagem de clientes, com busca no cabeçalho, ordenação e filtro por coluna;
   • o formulário de cliente em duas colunas, com o toast ao salvar;
   • o combo de status com os seis valores cadastrados na aula 03.
10. Volte ao Studio e abra o bloco Sync estrutural no painel. Ele lista as mudanças de estrutura (tabelas, CRUDs, menu e permissões) aplicadas ao ambiente. O status saudável é Estrutura sincronizada; logo após um publish a linha traz baseline via deploy.
11. Conheça os três botões e a diferença entre eles:

    Botão	O que faz	Quando usar
    Testar agora	Publica o código e preserva o banco; migrations novas rodam sozinhas	Sempre que mexer em tela, menu ou permissão
    Popular dados de teste	Gera as linhas dos seeds de dev no ambiente que está no ar	Quando o sistema estiver vazio demais para testar — antes de cadastrar à mão
    Recriar ambiente (reseta o banco de dados)	Apaga o banco e semeia de novo	Só para zerar os dados ou trocar de engine/versão

12. Abra Histórico para ver as publicações anteriores, com data, modo e resultado.
13. Deixe o ambiente no ar. Da aula 07 em diante, o fim de cada aula é sempre o mesmo: Testar agora e conferir o resultado na aplicação.

Erros comuns

Checklist de encerramento

• O painel mostra ONLINE e uma URL ativa.
• A senha do admin foi definida por mim e está salva.
• O deploy terminou com o aviso Teste Online publicado e sem erro de migration.
• Popular dados de teste rodou e listou as tabelas semeadas.
• Consigo entrar na aplicação com admin e a minha senha.
• A tira de módulos mostra Operação e Cadastros (e Relatórios quando tiver tela).
• A listagem de clientes abre com a busca no cabeçalho e o botão Novo.
• O formulário da ordem de serviço abre com as grades de serviços e peças.
• O combo de status mostra os seis status da aula 03.
• Sei a diferença entre Testar agora, Popular dados de teste e Recriar ambiente (reseta o banco de dados).

← Aula 05 — Módulos, menu, grupos e perfis · Aula 07 — Formulário de Cliente →

Objetivo

Transformar o ClienteForm gerado na aula 04 num cadastro que preenche o endereço sozinho pelo CEP, aceita CPF e CNPJ no mesmo campo, mascara o telefone e devolve a pessoa à listagem depois de salvar.

O que você terá no fim

• ClienteForm com o campo cep do tipo CEP e mapeamento para logradouro, bairro, cidade e uf.
• telefone com Máscara de digitação = Telefone (dinâmico).
• cpf_cnpj com Máscara de digitação = CPF/CNPJ (dinâmico) — a carteira da Assistec tem empresa e pessoa física.
• O campo CNPJ conhecido: o que ele traz da Receita e por que ele não serve quando a mesma tabela guarda os dois documentos.
• Após salvar configurado para atualizar a linha em ClienteList e mostrar uma mensagem.
• O cadastro funcionando no Teste Online com os dados fictícios do curso.

Studio › Início › ClienteForm › Visual

Studio › ClienteForm › Propriedades › CEP

Studio › ClienteForm › CEP › Configurar mapeamento

Studio › ClienteForm › Propriedades › Apresentação

Studio › ClienteForm › Propriedades › Apresentação

Studio › ClienteForm › Propriedades da página › Após salvar

App › Cadastros › Clientes › Novo

Passo a passo

1. Abra ClienteForm. Dois caminhos: na aba Início, digite ClienteForm em Buscar telas, códigos, controllers… e clique na linha ClienteForm.blade.php; ou, no rail, abra Arquivos e procure o arquivo na árvore. A página abre numa aba própria, na visão Visual — ao lado ficam PHP e Blade, que mostram o mesmo arquivo em código.
2. A tela do editor tem três colunas: Componentes (a paleta, com Estrutura do Formulário, Entrada de Dados, Seleção, Busca, Seleção (DB), Arquivos, Interface), o canvas no meio e Propriedades à direita. Enquanto nada está selecionado, o painel diz Selecione um componente.
3. Ao lado de Componentes existe a aba Árvore: a lista de tudo que a tela tem, na ordem, com o nome do campo entre parênteses (input-field (cep)). Clicar numa linha seleciona o componente — é o caminho mais rápido num formulário cheio.
4. Clique no campo cep (no canvas ou na Árvore). O painel mostra, de cima para baixo: o caminho (form › form-section › form-grid › input-field "cep"), o combo de tipo, e as abas EVENTOS e PROPRIEDADES. Dentro de PROPRIEDADES ficam as seções Identificação, Validação, Comportamento e Apresentação — o número ao lado do título é quantas propriedades daquela seção estão preenchidas.
5. Abra o combo de tipo (ele mostra Texto / mad-input-field). Ele tem um campo Buscar… e agrupa as opções como a paleta. Escolha CEP (grupo Entrada de Dados). Se a troca precisar descartar alguma propriedade, o editor pergunta antes em Trocar componente? — de Texto para CEP com só nome e rótulo preenchidos, não pergunta.
6. Com o cep selecionado, role o painel até o cartão MAPEAMENTO. Ele fica abaixo das seções, não dentro de Comportamento. Enquanto está vazio, mostra Nenhum mapeamento configurado. Clique em Configurar mapeamento.
7. No modal Mapeamento de auto-fill — CEP, clique em Mapear automaticamente. Ele cria estas quatro linhas:

   Campo da API	Campo do formulário
   logradouro (sem tipo)	logradouro — Logradouro
   bairro	bairro — Bairro
   cidade (texto)	cidade — Cidade
   uf	uf — Uf

   Use Adicionar linha para o que faltar e a lixeira para o que sobrar. Confirme em Salvar.

8. Olhe a lista de Campo da API: além de cep, bairro, uf e companhia, ela tem rua (tipo + logradouro), estado (nome completo), cidade_cod_ibge, estado_cod_ibge, cidade_id (resolvido) e estado_id (resolvido). Os dois últimos existem para quando cidade e uf são chaves estrangeiras para tabelas próprias — aí o auto-fill grava o id em vez do texto, e o modal ganha a seção Resolução no banco (cidade/estado). No nosso modelo as duas colunas são texto, então essa seção não aparece.
9. Ainda no cep: Busca automática no blur já vem ligada (é a chave embaixo do mapeamento). Em Comportamento existe Remover máscara ao salvar — deixe desligada: queremos 01001-000 gravado com o traço.
10. Selecione cpf_cnpj e troque o tipo para CNPJ, só para conhecer o campo. Ele traz dois cartões próprios:
    • TIPO DE CONSULTA, com Básico (Razão social, telefone, endereço. Resposta rápida.) e Completo (+ situação cadastral, CNAEs, QSA, capital social. Mais lento.);
    • Mapeamento de auto-fill, igual ao do CEP, com Configurar mapeamento e Busca automática no blur (aqui, 14 dígitos).
11. Abra Configurar mapeamento e clique em Mapear automaticamente. Ele acerta o endereço e o telefone (ddd_telefone_1 (principal) → telefone — Telefone), mas não cria a linha da razão social: a coluna da nossa tabela se chama nome_razao_social, e o automático só casa nomes iguais. Use Adicionar linha e monte razao_social → nome_razao_social — Nome Razao Social.
12. Agora a decisão de projeto: a Assistec atende quatro empresas e uma pessoa física (Marina Costa). O campo CNPJ valida 14 dígitos e não tem Máscara de digitação — ele é o caminho certo quando a carteira é só de pessoa jurídica. Como a nossa é mista, volte o tipo de cpf_cnpj para Texto e resolva pela máscara, no passo 14.
13. Selecione o campo telefone e abra Apresentação. Além de Largura, Ícone e Forçar digitação, existe Máscara de digitação: uma lista que começa em — Alias pronto — e traz CPF — 999.999.999-99, CNPJ — 99.999.999/9999-99, CPF/CNPJ (dinâmico), CEP — 99999-999, Telefone (dinâmico), Data — 99/99/9999, Hora — 99:99, Data + Hora — 99/99/9999 99:99, Placa — AAA-9999 e RG — 99.999.999-9. Escolha Telefone (dinâmico): o campo passa a formatar (11) 90000-0000 enquanto a pessoa digita, e aceita fixo de oito dígitos também.
14. Repita em cpf_cnpj com CPF/CNPJ (dinâmico). Essa máscara alterna o formato pelo tamanho do que foi digitado — é o que permite guardar CPF e CNPJ na mesma coluna. Embaixo da lista existe ou pattern custom, para máscara própria (9 = dígito, A = letra, * = alfanumérico). As duas são mutuamente exclusivas.
15. Ainda em cpf_cnpj, olhe as outras seções: Validação tem Obrigatório; Comportamento tem Placeholder, Valor padrão, Dica e Somente leitura. É tudo o que decide o estado de um campo pelo painel.
16. Na tira do editor, clique na engrenagem Propriedades da página. O painel da direita troca de conteúdo e mostra Título, Tipo de exibição, Tamanho, depois Após salvar e Menu e módulos.
17. Em Após salvar → Ação, escolha Atualizar a linha na listagem (as outras são Fechar e avisar, Ir para outra página e Continuar no formulário). Em Listagem, escolha ClienteList ★ — a estrela marca as listagens da mesma tabela.
18. Em Mensagem de sucesso, escreva Cliente salvo. Vazio significa salvar em silêncio. O campo só grava quando você sai dele (ou aperta Enter).
19. Clique em Salvar (Cmd+S). No rail, abra Teste online e clique em Testar agora.
20. No app, entre em Cadastros → Clientes → Novo e cadastre: Padaria Pão Dourado Exemplo, CEP 01001-000, número 100, telefone (11) 90000-0000, e-mail contato@paodourado.exemplo.com.br.
21. Confira: ao sair do campo de CEP, logradouro, bairro, cidade e uf se preenchem sozinhos; o telefone sai mascarado; ao salvar, a mensagem aparece e a linha entra na listagem. Cadastre do mesmo jeito os outros quatro clientes do curso — Clínica Vida Exemplo, Condomínio Jardim Exemplo, Mercado Bom Preço Exemplo e Marina Costa (pessoa física, CPF 000.000.000-00) —, variando só o telefone ((11) 91000-0000, (11) 93000-0000, (11) 94000-0000, (11) 92000-0000). São os cinco que as aulas seguintes usam.

Erros comuns

Checklist de encerramento

• O campo cep aparece no painel como CEP, com lupa ao lado no canvas.
• Configurar mapeamento do CEP tem as quatro linhas (logradouro, bairro, cidade, uf).
• telefone tem Máscara de digitação = Telefone (dinâmico).
• cpf_cnpj está como Texto com CPF/CNPJ (dinâmico).
• Após salvar está em Atualizar a linha na listagem, apontando ClienteList ★.
• Mensagem de sucesso preenchida.
• Página salva (Salvar (Cmd+S)) e Teste Online republicado (Testar agora).
• No app, o CEP 01001-000 preenche o endereço sozinho e o telefone sai mascarado.
• Os cinco clientes do curso (Padaria Pão Dourado Exemplo, Clínica Vida Exemplo, Condomínio Jardim Exemplo, Mercado Bom Preço Exemplo e Marina Costa) estão cadastrados.

← Aula 06 — Teste Online · Aula 08 — Listagem de Clientes →

Objetivo

Deixar o ClienteList gerado na aula 04 pronto para o dia a dia: as colunas certas, filtro no cabeçalho, barra de filtros, botões em cada linha e exportação em PDF com cabeçalho da empresa.

O que você terá no fim

• ClienteList com seis colunas úteis, rótulos legíveis e ordenação padrão.
• Filtro no cabeçalho da coluna uf, no tipo Opções fixas.
• A barra Filtros da Listagem conhecida (estilos Toolbar, Chips, Drawer…).
• Os dois botões de linha entendidos: um que navega e um que executa um método.
• Exportação em PDF com cabeçalho e rodapé próprios, a partir de um modelo pronto.

Studio › ClienteList › Propriedades › Colunas

Studio › ClienteList › Coluna uf › Filtro da coluna

Studio › ClienteList › Ações › Editar › Navegação

Studio › ClienteList › Propriedades da página › Exportação PDF

App › Cadastros › Clientes

Passo a passo

1. Abra ClienteList. No painel do meio, use a aba Árvore e clique em grid — é o jeito mais direto de selecionar a grade inteira.
2. O painel da direita mostra, nesta ordem: Regras de carregamento, Filtros, Propriedades (com Agrupamento, Ordenação, Paginação, Carregamento inicial e Layout), COLUNAS (N) e AÇÕES (N). No topo há ainda um atalho Configurar relatório, que reúne agrupamento e totais — assunto da aula 16.
3. Abra Layout e ligue Buscável, Exportável e Header Fixo. Ali também ficam Lado das ações, Config inline e Atualizável (que vale em telas que ficam abertas o dia inteiro).
   ⚠️ Clique na chavinha, não na linha. Nessas chaves o clique só conta em cima do interruptor; clicar no meio do rótulo não alterna nada e não avisa. O contador ao lado do nome da seção (Layout 4) é a conferência rápida: ele conta as propriedades ligadas.
4. Em Paginação, Itens por página vem em 15. Acima de 50 a tela começa a pesar.
5. Em Ordenação → Ordenação padrão, escolha Coluna = nome_razao_social e Direção = Crescente (A→Z). Coluna é um campo de busca (começa em *— escolha a coluna —*) e Direção é uma lista fechada que só destrava depois de a coluna ser escolhida — se a direção estiver cinza, é porque falta a coluna.
6. Abra COLUNAS. Cada linha mostra o rótulo em cima e, embaixo, o meta da coluna (nome_razao_social · sort · filter:text). As setas reordenam, o + Add cria e a lixeira (aparece ao passar o mouse) remove — com um Remover? / Sim antes. Remova id, tipo_pessoa, email, cep, logradouro, numero, complemento, bairro e observacoes. Devem sobrar seis:

   Campo	Label	Alinhamento
   nome_razao_social	Cliente	esquerda
   cpf_cnpj	CPF / CNPJ	esquerda
   telefone	Telefone	esquerda
   cidade	Cidade	esquerda
   uf	UF	centro
   ativo	Situação	centro

7. Clique numa coluna para abrir o painel dela: Identificação (Campo, Label, Largura, Alinhamento), Ordenação (Ordenável), Formato, Cálculo, Visibilidade, e os cartões FILTRO DA COLUNA e EDIÇÃO INLINE.
8. Label não é uma caixa de texto comum: é um botão que mostra o texto atual e o selo text. Clicando nele abre a janela Literal / i18n key — digite o novo rótulo e clique em Salvar texto. (Salvar e traduzir cria uma chave de tradução; é assunto da aula 24.)
9. Selecione a coluna uf e, no cartão FILTRO DA COLUNA, clique em Configurar filtro. O painel inteiro troca pelo filtro — repare no caminho no topo: … › col › Filtro. O botão ← volta.
10. Marque Filtrar por esta coluna e escolha o Tipo de filtro. São dez: Texto, Opções fixas, Combo de tabela, Busca no banco, Múltipla escolha, Data, Período, Número, Faixa numérica e Sim/Não. Para uf, Opções fixas. Embaixo ainda há Coluna filtrada (deixe vazio para filtrar pela própria coluna), Comparação (Igual a (padrão) aqui), Texto de ajuda no campo, a Prévia e o Blade gerado.
    ⚠️ Hoje o botão Adicionar opção não cria a linha. A opção nasce vazia e é descartada na hora de gravar, então a lista volta vazia. Enquanto isso não muda, a lista de opções precisa ser escrita na aba Blade da página (:filter-opts="['SP' => 'SP', 'RJ' => 'RJ', 'MG' => 'MG']" na <mad-col> do uf) — ou use Combo de tabela, quando a coluna aponta uma tabela.
11. Volte com o ← e confira cidade: ela já veio da geração em lote com Texto (busca por trecho), que é o que queremos. As seis colunas ficam então com o meta nome_razao_social · sort · filter:text, cpf_cnpj · sort · filter:text, telefone · sort · filter:text, cidade · sort · filter:text, uf · sort · filter:select e ativo · sort.
    Dica (opcional, fora do que a aula grava).ativo também aceita filtro, no tipo Sim/Não — ele pede Valor de "Sim" no banco e Valor de "Não" no banco. Deixamos a coluna sem filtro para manter a tela enxuta.
12. Na tira do editor, clique em Configurar Filtros da Listagem (o ícone azul de controles, que só aparece em listagem e relatório). No modal Filtros da Listagem:
    • ESTILO tem sete opções — Toolbar (Filtros inline + popovers), Chips, Formulário, Drawer, Modal, Sidebar ← e Sidebar →. Escolha Toolbar;
    • Título (opcional) aceita Filtros; Nome (ID, opcional) é o id do componente;
    • em Colunas da tabela, marque cidade e ativo (há atalhos Todas s/ PK e Nenhuma). Cada coluna marcada cria um filtro em Filtros declarados;
    • REGRAS DE FILTRO é onde se diz qual coluna cada filtro corta; enquanto estiver Nenhuma regra declarada., use + Adicionar Regra de Filtro.

    Feche em Fechar.

13. Abra AÇÕES (2). Os dois botões já existem — a geração em lote da aula 04 criou Editar e Excluir. Clique em Editar: em Navegação, o modo Escolher página tem Página = ClienteForm e Método, e Argumentos manda o id da linha. O modo Manual aceita ClienteForm::onEdit({id}) digitado à mão.
14. Clique em Excluir. A diferença está em qual grupo é preenchido:
    • Navegação → Navigate abre outra tela (é o botão de abrir);
    • Eventos → On Click chama um método PHP do controller da própria listagem.

    Ele vem com On Click = onDelete, confirmação Tem certeza que quer remover esse registro? e Variante vermelha.

15. Em Visibilidade, Exibir quando… esconde o botão nas linhas em que ele não faz sentido. Deixe para depois — o botão de excluir vale em toda linha.
16. Na tira do editor, clique na engrenagem Propriedades da página. A seção Exportação PDF só aparece em página de listagem ou de relatório. Ela mostra o selo Padrão do projeto enquanto nada foi personalizado. Clique em Configurar cabeçalho e rodapé….
17. O modal Cabeçalho e rodapé do PDF é um editor de arrastar e soltar, não um formulário:
    • à esquerda, o card Modelos prontos, a caixa ELEMENTOS (Texto, Logo / imagem, Nº de página, Data, Campo dinâmico), os chips de CAMPOS DISPONÍVEIS ({TITLE}, {SUBTITLE}, {DATE}, {PERIOD}, {FILTERS}, {TOTAL_REGISTER}, {APP_NAME}, {TENANT_NAME}, {UNIT_NAME}, {USER_NAME}), CAMPOS DO PROJETO e os ATALHOS do teclado;
    • no meio, Cabeçalho do PDF e Rodapé do PDF, cada um com Padrão do projeto / Personalizado / Sem cabeçalho, e a folha A4 com as faixas CABEÇALHO e RODAPÉ (cada uma com altura e respiro em mm);
    • à direita, as propriedades do elemento selecionado.

    Clique no cartão Modelos prontos: abre uma segunda janela com os modelos, cada um com um botão Usar este modelo. Escolha Corporativo clássico (Logo, título centralizado e paginação.). Os dois seletores viram Personalizado e a folha passa a mostrar o logo, o título e Página 1 de 12. Feche em Fechar.

18. De volta ao painel da grade, em Agrupamento, Título da exportação alimenta o {TITLE} das bandas do PDF e Subtítulo da exportação o {SUBTITLE}. Preencha o título com Clientes.
19. Clique em Salvar (Cmd+S). No rail, abra Teste online e clique em Testar agora.
20. No app, entre em Cadastros → Clientes e confira: as seis colunas, o filtro no cabeçalho de UF e os botões da linha. Digite Exemplo na busca do topo — a lista fecha nos cinco clientes do curso (1–5 de 5), separando-os das linhas do Faker.

Erros comuns

Checklist de encerramento

• Em Layout, Buscável, Exportável e Header Fixo estão ligados.
• Ordenação padrão aponta nome_razao_social em ordem crescente.
• A listagem mostra seis colunas, com UF centralizada.
• Os rótulos estão legíveis (Cliente, CPF / CNPJ, Situação).
• uf está com Filtrar por esta coluna e Opções fixas.
• Os dois botões de linha existem e o de excluir pede confirmação.
• O cabeçalho do PDF está Personalizado, com um modelo aplicado.
• Página salva (Salvar (Cmd+S)) e Teste Online republicado (Testar agora).

← Aula 07 — Formulário de Cliente · Aula 09 — OS com serviços e peças (master-detail) →

Objetivo

Deixar a ordem de serviço com tudo que ela precisa numa tela só: os serviços executados, as peças aplicadas e os anexos — cada linha filha calculando o seu subtotal e somando no rodapé.

O que você terá no fim

• OrdemServicoForm com dois Field List (os_servico_item, os_peca_item) e um Detail Form (os_anexo), com rótulos legíveis.
• Coluna subtotal calculada por fórmula, só leitura e somando no rodapé, nas duas listas.
• Anexos em gaveta, com o campo de arquivo gravando o caminho numa pasta do projeto.
• Após salvar em Continuar no formulário, porque quem abre uma OS volta a ela.
• No app: uma OS de exemplo fechando 600,00 de serviços e 240,00 de peças.

Studio › + Criar novo › Nova página › Formulário › Cadastro com Detalhe

Studio › OrdemServicoForm › Field List flOsServicoItem

Studio › OrdemServicoForm › Coluna Subtotal › Cálculo

Studio › OrdemServicoForm › Coluna Subtotal › Totalizador

Studio › OrdemServicoForm › dfOsAnexo › campo arquivo

App › Operação › Ordem de Serviços › Editar

Passo a passo

1. Só para mostrar o caminho: na tira do Studio, clique no + (Criar novo) e escolha Nova página. O assistente ocupa a tela inteira (não é uma janelinha) e tem três passos: Tipo, Variação e Configuração.
   • Passo 1: Formulário (Cadastros e edições — CRUD completo).
   • Passo 2: Cadastro com Detalhe (Master-detail com tabelas filhas).
   • Passo 3: Base de dados assistec e Tabela ordem_servico. Assim que a tabela é escolhida nasce a lista Tabelas detalhe:, com todas as tabelas que apontam para ordem_servico — os_servico_item, os_peca_item, os_anexo, os_historico e os_apontamento —, cada uma com o (via ordem_servico_id) e um seletor field-list / detail-form. Marcar a caixa inclui aquela tabela na tela.
   • Saia em Cancelar (canto superior direito). Não crie a página: ela já existe desde a aula 04, e criar de novo deixaria duas telas para a mesma tabela.
2. Abra OrdemServicoForm. No painel do meio, use a aba Árvore: a tela já tem field-list (flOsServicoItem), field-list (flOsPecaItem) e detail-form (dfOsAnexo) — a geração em lote da aula 04 montou os três, cada um numa seção própria.
3. Selecione flOsServicoItem. Em Identificação:
   • Nome (flOsServicoItem) é o identificador usado nos hooks do formulário (onSaveDetail/onLoadDetail);
   • Label Botão: troque Adicionar item por Adicionar serviço.

   Em Comportamento, Dica aceita um texto de apoio (Um serviço por linha) que sai abaixo da lista, e ali também ficam Addable, Removable e Sortable.

4. Em Fonte de dados, confira Tabela detalhe = os_servico_item com FK: ordem_servico_id. Os dois aparecem bloqueados — o aviso diz: *"Tabela detalhe bloqueada. Para trocar, remova este Field List e adicione um novo."* Embaixo estão Editar N colunas, Coluna FK e Model.
5. Abra COLUNAS. Clique em cada coluna e ajuste o Label em Identificação:

   Campo	Label
   servico_id	Serviço
   quantidade	Qtd
   preco_unitario	Preço
   desconto_pct	Desc. %
   subtotal	Subtotal
   observacao	Observação

   A coluna id fica como está: ela é hidden e não aparece para a pessoa.

6. O painel de uma coluna tem dois blocos: o cartão COLUNA (Identificação com Campo, Label e Largura, mais Outras) e o cartão CAMPO, cujo topo é um seletor de tipo (text, number, numeric, money, date, discount, combo_input, select, dbcombo, hidden, email, tel, checkbox, radio, textarea, file). Dentro dele: Validação, Comportamento, Formato e Cálculo.
7. Selecione a coluna Serviço. Ela já nasce dbcombo e com a Fonte de dados preenchida: Database assistec, Tabela (Model) servico, Chave id, Display {nome} e Ordenar por nome ASC. É isso que faz o combo mostrar o nome do serviço em vez do código. Ali embaixo ainda há Combo dependente e Regras de carregamento — assunto da aula 10.
8. Selecione a coluna Subtotal, abra Cálculo e clique em Adicionar fórmula. No modal Editar fórmula de cálculo, escreva:

   round({quantidade} * {preco_unitario} * (1 - {desconto_pct} / 100), 2)

   CAMPOS DISPONÍVEIS insere a coluna já entre chaves (a lista mostra o rótulo, mas o que entra na fórmula é o nome da coluna); FUNÇÕES traz round, max, min, abs, floor, ceil, if e discount. Se você citar uma coluna que não existe, aparece o aviso ⚠ Validação embaixo da caixa. Clique em Salvar.

   Ao gravar a primeira fórmula, a plataforma liga o Read-only da coluna sozinha — é o comportamento certo: campo calculado que aceita digitação é campo que vai ser sobrescrito na frente do usuário. Confira em Comportamento.
9. Ainda em Subtotal, vá até o fim do painel: o cartão TOTALIZADOR explica que a linha de totais mostra *soma ou contagem — nunca os dois juntos*. Ligue Somar valores; Contar linhas fica bloqueado na mesma hora.
10. Repita em flOsPecaItem: Label Botão Adicionar peça, rótulos Peça, Qtd, Preço, Subtotal e Nº de série, e a fórmula mais simples (não há desconto aqui):

    round({quantidade} * {preco_unitario}, 2)

    Ligue Somar valores no Subtotal dela também.

11. Selecione dfOsAnexo. Em Identificação: Nome dfOsAnexo, Modo com as três opções inline / modal / drawer (deixe drawer), Label Botão Adicionar anexo e Título do Form Anexo da OS. Em Fonte de dados, a Tabela detalhe os_anexo também vem travada, com o botão Escolher colunas e campos.
12. Escolher colunas e campos abre um assistente de três passos — Escolher tabela detalhe, Selecionar colunas de os_anexo e Dispor campos no formulário (com COLUNAS DO FORMULÁRIO em 1, 2, 3 ou 4 e os cards arrastáveis). Ele já vem resolvido: oito campos, duas colunas. Feche em Esc se for só olhar.
13. Abra o detail-form na Árvore até chegar nos campos. Repare no que o gerador escolheu sozinho, pelo tipo e pelo nome da coluna:
    • arquivo e nome_arquivo → Upload (mad-file-field);
    • imagem → Imagem (mad-image-field);
    • assinatura_base64 → Assinatura (mad-signature-field) — assunto da aula 12.
14. Selecione o campo arquivo e abra Armazenamento de dados:
    • Tipos aceitos é uma fileira de chips (Imagens (todas), PNG, JPEG, WebP, GIF, SVG, PDF, Word, Excel, CSV, ZIP/RAR, Áudio, Vídeo) mais Outros (CSV de MIME/extensão). Sem nenhum marcado, o campo aceita qualquer arquivo;
    • Tamanho máximo aceita 10MB;
    • Tipo de gravação já vem em Armazenar caminho do arquivo na coluna — é o que faz o arquivo ser guardado de verdade;
    • Pasta de upload vem preenchida com os_anexos;
    • Modo de renomeação evita que dois arquivos com o mesmo nome se atropelem.
15. Na tira do editor, abra a engrenagem Propriedades da página → Após salvar. A Ação tem quatro opções: Atualizar a linha na listagem, Fechar e avisar, Ir para outra página e Continuar no formulário. Escolha Continuar no formulário e preencha Mensagem de sucesso com OS salva.
16. Clique em Salvar (Cmd+S). No rail, abra Teste online e clique em Testar agora.
17. No app, em Operação → Ordem de Serviços, abra (ou crie) a OS OS-2026-001 da Padaria Pão Dourado Exemplo e monte: Visita técnica diagnóstica (1 × 150,00) e Limpeza de câmara fria (1 × 450,00); em peças, Gás R-410A kg (2 × 120,00). O rodapé dos serviços fecha em 600,00 e o das peças em 240,00.

Erros comuns

Checklist de encerramento

• OrdemServicoForm tem dois Field List e um Detail Form.
• Os dois Field List têm Tabela detalhe e Coluna FK preenchidos.
• Os botões dizem Adicionar serviço e Adicionar peça.
• Serviço e Peça são combos de banco, mostrando o nome e não o código.
• Subtotal tem fórmula, está Read-only e soma no rodapé — nas duas listas.
• O Detail Form de anexos abre em gaveta com o título Anexo da OS.
• O campo arquivo está em Armazenar caminho do arquivo na coluna, com Pasta de upload preenchida.
• Após salvar está em Continuar no formulário.
• No app, a OS de exemplo fecha em 600,00 de serviços e 240,00 de peças.
• Página salva (Salvar (Cmd+S)) e Teste Online republicado (Testar agora).

← Aula 08 — Listagem de Clientes · Aula 10 — DB Combo avançado →

Objetivo

Fazer os combos do cabeçalho da OS trabalharem juntos: o equipamento só mostra o que é do cliente escolhido, preenche o título da OS sozinho e deixa cadastrar um equipamento novo sem sair da tela.

O que você terá no fim

• cliente_id, equipamento_id e tecnico_id conferidos como DB Combo com Display legível.
• equipamento_id em cascata: só os equipamentos do cliente escolhido.
• Regras de carregamento no mesmo equipamento_id, cortando equipamento inativo sem a pessoa ver: o combo mostra só o que é do cliente *e* está ativo.
• Preenchimento de campos: escolher o equipamento preenche o titulo da OS.
• Sem resultados com os dois modos ativos: abrir o cadastro completo e cadastrar na hora.

Studio › OrdemServicoForm › cliente_id › Fonte de dados

Studio › OrdemServicoForm › equipamento_id › Combo dependente

Studio › OrdemServicoForm › equipamento_id › Preenchimento de campos

Studio › OrdemServicoForm › Sem resultados › Cadastro rápido inline

Studio › OrdemServicoForm › equipamento_id › Sem resultados

App › Operação › Ordem de Serviços › Novo

Passo a passo

1. Abra OrdemServicoForm e selecione cliente_id na Árvore. Ele já é um DB Combo (mad-dbcombo-field) — a geração em lote da aula 04 cria assim toda coluna que é chave estrangeira.
2. Abra Fonte de dados e confira o que veio pronto:
   • Database: assistec (o banco do projeto — não mexa);
   • Tabela (Model): cliente;
   • Chave: id — o valor que vai ser gravado;
   • Display: {nome_razao_social} — o texto que a pessoa lê;
   • Ordenar por: nome_razao_social, ASC.

   O Display aceita juntar colunas: {nome_razao_social} - {cidade} ajuda quando há nomes parecidos. O mesmo vale para tecnico_id (tecnico, {nome}) e equipamento_id (equipamento, {nome}).

3. Selecione equipamento_id e abra Combo dependente:
   • Depende de = cliente_id — o campo pai, que a pessoa preenche antes;
   • Coluna FK = cliente_id — a coluna da tabela equipamento que aponta para o pai.

   Os dois são obrigatórios. Preencher só o Depende de faz o sistema filtrar por uma coluna que não existe, e a lista volta sempre vazia.

   Os dois controles são diferentes de propósito: Depende de é um campo de busca (ele lista os outros combos do formulário) e Coluna FK é uma lista fechada, com as chaves estrangeiras da tabela do combo. Num combo cuja tabela não tem FK nenhuma, ele aparece com o aviso Tabela sem FKs.
4. Continue no equipamento_id e abra Regras de carregamento → Configurar filtros. O construtor abre com o Grupo raiz vazio (AND / OR):
   • clique em Regra;
   • Coluna = ativo (boolean), Operador = =, Valor = Valor literal true;
   • o Preview do PHP gerado mostra, na hora, :filters="[['ativo', '=', true]]";
   • clique em Aplicar.

   Cascata e regra somam: o combo passa a listar o que é do cliente escolhido *e* está ativo. No painel, REGRAS DE CARREGAMENTO ganha o selo 1.

   Por que o preview muda de forma.Num combo sem cascata a regra vira uma consulta pronta (:query="$filter_<campo>", com a declaração acima da tag). Num combo com cascata ela vira a lista de condições :filters — é a forma que o framework aceita ao lado do depends-on. Você não escolhe: a plataforma decide pela presença do Depende de. Confira pela aba Blade. Se a sua versão ainda gravar :query num campo com Depende de, a tela inteira deixa de abrir com a prop :query não suporta depends-on (cascata). Nesse caso mova a regra para o combo pai (cliente_id, sem cascata) até atualizar a plataforma. O botão Grupo permite aninhar condições (um OR dentro do AND, por exemplo).
5. Abra a seção Preenchimento de campos e clique em Configurar. O modal Preenchimento de campos já abre com uma linha em branco — não clique em Adicionar campo antes de preencher essa, ou você fica com uma linha vazia sobrando. Na linha:
   • CAMPO DE DESTINO = titulo — Titulo (uma lista com os campos do formulário);
   • ORIGEM DO VALOR = nome (as colunas da tabela do combo, com busca);
   • TRANSFORMAÇÃO (OPCIONAL) — deixe vazia (há MAIÚSCULAS, minúsculas, Título, Aparar, Moeda, Data (formato), Número (casas), Máscara e método PHP próprio);
   • marque SÓ VAZIO.

   Clique em Salvar.

   Preenchimento de camposexiste no DB Combo, no DB Select e no Unique Search — sempre dentro de um <mad-form>. Nas colunas de um Field List o equivalente é o evento On Change da coluna, que chama um método PHP.
6. Abra a seção Sem resultados. Em MENSAGEM (CABEÇALHO), escreva Não encontrado. Cadastre agora:. Os dois modos começam INATIVO; clicar no card abre a configuração dele.
7. Modo 1 — card Abrir formulário completo:
   • Formulário = EquipamentoForm;
   • Método (abre o form) fica por conta da plataforma (o resumo mostra EquipamentoForm::show);
   • em APARÊNCIA DO BOTÃO dá para trocar Label, Ícone e as classes CSS.

   Clique em Salvar. O card passa a mostrar ATIVO.

8. Modo 2 — card Cadastro rápido inline:
   • Formulário de cadastro = EquipamentoForm. O Método (gerado) aparece ao lado, em cinza: onQuickSaveEquipamento. Ele é gerado no formulário escolhido — deixe o campo vazio; só preencha se quiser um método próprio (Avançado (Classe::método));
   • em CAMPOS, clique em Adicionar primeiro campo. O campo nasce como campo_1; o Nome é escolhido no painel da direita, numa lista com as colunas da tabela (o atalho Digitar o nome manualmente libera digitar). Crie nome, tipo Texto;
   • clique em adicionar e crie o segundo campo, cliente_id, tipo DBCombo (FK).

   Clique em Salvar.

   A tabela equipamento tem cliente_id obrigatório. Sem esse campo no mini-formulário, o cadastro rápido falha na hora de salvar — é a pegadinha mais comum do recurso. Quando a tabela exige muita coisa, use só o modo 1.
9. De volta ao painel, a seção Sem resultados mostra os dois cards em ATIVO, com o método de cada um (EquipamentoForm::show e EquipamentoForm::onQuickSaveEquipamento) e a contagem 2 CAMPOS.
10. Clique em Salvar (Cmd+S). No rail, abra Teste online e clique em Testar agora.
11. No app, abra Operação → Ordem de Serviços → Novo e confira, nesta ordem:
    • o combo Cliente abre com uma caixa de busca — é um combo próprio do sistema gerado, não o <select> cinza do navegador;
    • Equipamento começa vazio e só se enche depois do cliente;
    • escolhendo Padaria Pão Dourado Exemplo, o equipamento mostra só Câmara fria 01;
    • escolhendo a câmara fria, o Titulo da OS se preenche sozinho;
    • trocando o cliente, o equipamento limpa e recarrega;
    • digitando um equipamento que não existe, aparecem a mensagem e os dois botões.

Erros comuns

Checklist de encerramento

• cliente_id, equipamento_id e tecnico_id são DB Combo com Display legível.
• equipamento_id tem Depende de e Coluna FK preenchidos.
• equipamento_id tem uma regra em Regras de carregamento cortando ativo = true, e a aba Blade mostra :filters="[['ativo', '=', true]]" na tag — sem nenhum :query.
• O Preenchimento de campos tem a linha titulo ← nome, com SÓ VAZIO marcado.
• Sem resultados tem a mensagem e os dois cards em ATIVO.
• O Cadastro rápido inline tem os campos nome e cliente_id.
• No app, escolher o cliente reduz o combo de equipamento e o Titulo se preenche.
• Página salva (Salvar (Cmd+S)) e Teste Online republicado (Testar agora).

← Aula 09 — OS com serviços e peças (master-detail) · Aula 11 — Wizard de abertura de OS →

Objetivo

Criar uma tela de abertura de OS em etapas, com validação a cada passo, para quem atende o telefone não ter que encarar um formulário de vinte campos de uma vez.

O que você terá no fim

• Página Abertura de OS (tipo Formulário, variação Wizard) no módulo Operação.
• Três etapas nomeadas: Cliente e equipamento, Problema e Serviços previstos — mais a etapa Resumo, que a plataforma acrescenta sozinha.
• A terceira etapa gravando numa tabela própria (os_servico_item), pela chave estrangeira.
• Gravação No final: nada entra no banco enquanto a última etapa não for confirmada.
• Validação por etapa funcionando no Teste Online.

Studio › + Criar novo › Nova página › Formulário › Variação

Studio › Nova página › Wizard › Configuração

Studio › Abertura de OS › Visual

App › Operação › Abertura de OS

Passo a passo

1. Na tira do Studio, clique no + (Criar novo) → Nova página. No passo Tipo, clique em Formulário.
2. No passo Variação, as cinco opções aparecem com a descrição de cada uma. Clique em Wizard (Formulário em etapas com validação por passo) — o card escolhido fica com um ✓ — e depois em Continuar.
3. No passo Configuração, escolha Base de dados assistec e Tabela = ordem_servico.
4. A seção Etapas nasce com duas linhas já preenchidas (Dados gerais e Complemento). Cada linha tem o campo de título e, ao lado, o seletor Tabela desta etapa. Renomeie as duas e clique em + Etapa para criar a terceira:

   #	Título da etapa	Tabela desta etapa
   1	Cliente e equipamento	Tabela principal
   2	Problema	Tabela principal
   3	Serviços previstos	os_servico_item · FK ordem_servico_id

   A dica ao lado explica o que muda: *Etapa com tabela grava numa tabela própria (FK pro master)*.

   ⚠️ O campo de título fica bem estreito quando alguma linha tem uma tabela de nome longo (os_servico_item · FK ordem_servico_id): o seletor empurra o campo de texto. O texto continua lá e é gravado normalmente — clique dentro e use as setas para conferir.
5. Em Gravação, escolha No final. A dica ao lado muda conforme a escolha:
   • No final — Transação única no Salvar final (tudo ou nada);
   • A cada etapa — Avançar grava a etapa — processo retomável, pode deixar registro parcial.
6. Preencha Nome do item de menu com Abertura de OS, Classe de controle com AberturaOsWizard, Route com /abertura-os e Módulo com Operação. Deixe Exibir no menu em Sim e clique em Criar página.
   O painel SERÁ GERADO, à direita, mostra o que vai sair: app/Controllers/AberturaOsWizard.php, app/Views/operacao/AberturaOsWizard.mad e a rota /abertura-os. O arquivo no Explorer, porém, aparece com o nome derivado da rota (abertura-os-wizard.blade.php) — e o item na lista de telas leva o nome do menu, Abertura de OS.
7. No canvas, as etapas aparecem empilhadas, cada uma com o seu selo e a sua área de soltar. O aviso no topo lembra: runtime mostra 1 etapa por vez — aqui todas ficam visíveis pra editar. Repare no contador: Wizard · 4 etapas — a plataforma acrescenta uma etapa Resumo no fim, para a pessoa conferir antes de gravar.
8. O gerador põe TODOS os campos da tabela na primeira etapa. A etapa 2 nasce vazia. O trabalho da aula é distribuir: arraste da etapa 1 para a etapa 2 o que é sobre o problema (tipo, prioridade, descricao_problema, dt_agendada) e apague da etapa 1 o que só faz sentido depois do atendimento (descricao_solucao, dt_fim, progresso, horas_trabalhadas, os campos de valor, status_aprovacao) — esses continuam no OrdemServicoForm da aula 09.
   As colunas numero, titulo, cliente_id, status_os_id, descricao_problema e dt_abertura são obrigatórias no banco. Toda coluna obrigatória precisa continuar em alguma etapa — nem que seja com valor padrão. Se ficar de fora, o wizard chega ao fim e o salvamento falha sem ter onde mostrar o erro.
9. Clique no selo de uma etapa para abrir o painel dela: Chave, Título, Ícone e Descrição. A Chave é o identificador estável (cliente_e_equipamento), gerado a partir do título — é ela que a validação por etapa usa. Mude o Título à vontade; a Chave, só com motivo.
10. Selecione o bloco Wizard (o selo de fora) para ver Indicador — numbers, dots, arrows ou progress —, Indicador clicável e a mesma Gravação escolhida no assistente. Deixe Indicador clicável ligado: a pessoa volta para conferir o que já preencheu.
11. A etapa 3 já nasceu ligada a os_servico_item: ela é uma seção de detalhe com os campos da tabela filha prefixados (os_servico_item__servico_id, os_servico_item__quantidade…). Deixe só o que a abertura precisa — serviço, quantidade e preço — e apague o resto.
12. Clique em Salvar (Cmd+S). No rail, abra Teste online e clique em Testar agora.
13. No app, entre em Operação → Abertura de OS e confira:
    • o indicador das etapas aparece no topo, com a etapa 1 em destaque;
    • clicar em Avançar sem preencher mostra o aviso Corrija os erros antes de continuar e marca cada campo obrigatório em vermelho, com o texto O campo <nome> é obrigatório.;
    • preenchendo tudo, a etapa 2 abre e o indicador marca a 1 como concluída;
    • na etapa 3, adicionar um serviço soma no rodapé;
    • Salvar grava a OS e os itens de uma vez — e não antes.
14. Abra Operação → Ordem de Serviços e confirme que a OS aberta pelo wizard está lá, com os itens.

Erros comuns

Checklist de encerramento

• A página Abertura de OS existe, no módulo Operação e visível no menu.
• As três etapas estão nomeadas, e a terceira aponta os_servico_item.
• Gravação está em No final.
• Os campos foram distribuídos entre as etapas 1 e 2 — nenhuma coluna obrigatória ficou de fora.
• Cada etapa tem uma Chave estável.
• No app, avançar sem preencher mostra o erro e não muda de etapa.
• A OS aberta pelo wizard aparece na listagem, com os itens.
• Página salva (Salvar (Cmd+S)) e Teste Online republicado (Testar agora).

← Aula 10 — DB Combo avançado · Aula 12 — Consulta de OS + assinatura, scanner e imagem →

Objetivo

Montar uma tela de consulta da OS — cabeçalho em leitura e as listagens das tabelas filhas — e conhecer os campos que só existem no celular: assinatura na tela, leitura de código de barras e foto com recorte.

O que você terá no fim

• Página Consulta de OS (tipo Formulário, variação Consulta) no módulo Operação, com três Listagens detalhe: os_servico_item, os_peca_item e os_historico.
• O campo assinatura_base64 dos anexos como Assinatura, com altura, modos e câmera.
• O campo codigo_lido como Scanner, no formato Os dois.
• O campo imagem como Imagem, com recorte e limite de tamanho.
• Clareza sobre quando usar Upload Múltiplo em vez de um formulário por linha.

Studio › + Criar novo › Nova página › Formulário › Variação

Studio › Nova página › Consulta › Configuração

Studio › OrdemServicoForm › dfOsAnexo › assinatura_base64

Studio › OrdemServicoForm › dfOsAnexo › codigo_lido

App › Operação › Consulta de OS

Passo a passo

1. Na tira do Studio, clique no + (Criar novo) → Nova página → Formulário. No passo Variação, clique em Consulta (Visualização com listagens detalhe) e depois em Continuar.
2. No passo Configuração, escolha Base de dados assistec e Tabela = ordem_servico. A seção Listagens detalhe: aparece com todas as tabelas que apontam para ela, cada uma com o (via ordem_servico_id) e uma caixa de marcação. Marque os_servico_item, os_peca_item e os_historico.
   Repare na diferença para a aula 09: no Cadastro com Detalhe a seção se chama Tabelas detalhe e cada linha tem um seletor field-list / detail-form. Na Consulta não há seletor — tudo vira listagem, porque a tela é de leitura.
3. Preencha Nome do item de menu com Consulta de OS, Classe de controle com ConsultaOsForm, Route com /consulta-os e Módulo com Operação. Deixe Exibir no menu em Sim e clique em Criar página.
4. No canvas, a tela nasce com o cabeçalho da OS e as três listagens. Selecione um campo do cabeçalho (numero, cliente_id, titulo) e, em Comportamento, confirme Somente leitura. Dois caminhos valem aqui:
   • Somente leitura no próprio campo — mantém a aparência de campo, sem digitação;
   • trocar o tipo para Display — vira texto puro, sem caixa.

   Use Display no que é só informação (numero, dt_abertura) e Somente leitura no que a pessoa reconhece como campo.

5. Abra OrdemServicoForm — é lá que a tabela os_anexo é editada, pelo Detail Form dfOsAnexo que você montou na aula 09. Na Árvore, abra detail-form (dfOsAnexo) → detail-fields → form-grid para chegar nos campos.
   Repare no que o gerador já escolheu pelo nome e pelo tipo da coluna: assinatura_base64 nasceu Assinatura (mad-signature-field), imagem nasceu Imagem (mad-image-field) e arquivo/nome_arquivo nasceram Upload (mad-file-field). Só codigo_lido nasce como Texto.
6. Selecione assinatura_base64. Confira o tipo Assinatura no combo do topo e configure:
   • Aparência → Altura 200px, Largura 100%;
   • Comportamento → Modos disponíveis draw,type,upload (desenhar, digitar o nome ou enviar uma imagem) e Permitir câmera ligado;
   • Armazenamento de dados — deixe como está: o desenho é gravado direto na coluna, que é texto longo.
7. Selecione codigo_lido e troque o tipo para Scanner (o combo do topo do painel; busque por "Scanner"). Abra a seção Formato e escolha Os dois — as alternativas são Só QR e Só código de barras. O campo continua aceitando digitação, para quem não tem câmera.
8. Selecione imagem (tipo Imagem) e abra Armazenamento de dados: Tipo de gravação em Armazenar caminho do arquivo na coluna, Pasta de upload, os Tipos aceitos só em imagens e Tamanho máximo 5MB. No app, esse campo vira a área *"Arraste uma imagem ou clique para selecionar"*, já anunciando IMAGE/PNG, IMAGE/JPEG, IMAGE/GIF · Máx 5MB.
9. Só para conhecer o caminho alternativo: um Upload Múltiplo tem, em Armazenamento de dados, o Modo de armazenamento com duas opções — comma (os caminhos em CSV numa única coluna) e table (uma linha por arquivo, numa tabela-pivô). É a escolha certa quando a pessoa manda muitos arquivos de uma vez e não precisa descrever cada um. Aqui, quem manda em os_anexo é o Detail Form — não adicione um Upload Múltiplo apontando a mesma tabela: dois componentes gravando a mesma tabela brigam entre si.
10. Clique em Salvar (Cmd+S). No rail, abra Teste online e clique em Testar agora.
11. No app, abra Operação → Ordem de Serviços, edite a OS de exemplo e clique em Adicionar anexo. A gaveta Anexo da OS mostra, lado a lado:
    • Tipo e Nome Signatario, campos de texto;
    • dois campos de upload (*Clique para enviar ou arraste aqui*);
    • a área de Imagem, com o limite anunciado;
    • a Assinatura, com o botão Desenhar, a tela de desenho e a paleta de cores;
    • o Scanner, que abre a câmera no celular e aceita digitação no computador.
12. Abra a Consulta de OS a partir de uma OS da listagem — a tela é de um registro e precisa do id. O cabeçalho vem em leitura, cada coluna como rótulo e valor (com — no que está vazio), e embaixo vêm as listagens dos serviços, das peças e do histórico daquela OS.

Erros comuns

Checklist de encerramento

• A página Consulta de OS existe, no módulo Operação e visível no menu.
• Ela tem as três Listagens detalhe: serviços, peças e histórico.
• Os campos do cabeçalho estão em Somente leitura (ou como Display).
• assinatura_base64 é Assinatura, com Modos disponíveis e Permitir câmera.
• codigo_lido é Scanner, no formato Os dois.
• imagem grava o caminho, com pasta, tipos aceitos e tamanho máximo.
• No app, Adicionar anexo abre a gaveta com upload, imagem e assinatura.
• No app, a Consulta de OS abre a partir de uma OS, com o cabeçalho em leitura e as listagens detalhe embaixo.
• Página salva (Salvar (Cmd+S)) e Teste Online republicado (Testar agora).

← Aula 11 — Wizard de abertura de OS · Aula 13 — Kanban de OS →

Objetivo

Transformar a tabela de ordens de serviço num quadro visual em que cada coluna é um status e arrastar o cartão muda o status no banco.

O que você terá no fim

• Página Quadro de OS (tipo Kanban) no módulo Operação, visível no menu do app.
• Seis colunas geradas a partir de status_os, na ordem e nas cores cadastradas na aula 03.
• Cartão mostrando número da OS, cliente, técnico e valor em moeda.
• Clique no cartão abrindo a OS no formulário da aula 09, e uma barra de filtros por técnico e por cliente no topo do quadro.
• Arrastar um cartão gravando ordem_servico.status_os_id — conferido no Teste Online.

Studio › + › Nova página › Kanban

Studio › + › Nova página › Kanban

Studio › Quadro de OS › Visual › Card do Kanban › Editor visual com preview

Studio › Quadro de OS › Configurar filtros do Kanban

App › Operação › Quadro de OS

Passo a passo

1. Na tira do Studio, clique em + → Nova página e escolha Kanban (Quadro com colunas de status) na lista de tipos.
2. O Kanban não tem variações: o clique no tipo já leva ao passo Configuração (o trilho da esquerda mostra Variação · Não aplicável, e o rodapé, Passo 3 de 3). Não há Continuar para clicar.
3. Deixe Base de dados no banco do projeto (assistec) e escolha em Tabela de etapas a tabela status_os. Cada linha dela vira uma coluna do quadro.
4. Em Tabela de itens, escolha ordem_servico (FK: status_os_id). O combo fica desabilitado até você escolher as etapas (dica selecione a tabela de etapas) e só lista tabelas que apontam para elas — sem FK, a dica vira nenhuma tabela com FK para etapas.
5. Preencha Nome do item de menu com Quadro de OS, Classe de controle com QuadroOsMad e Route com /quadro-os (os dois vêm sugeridos a partir da tabela de itens — OrdemServicoKanban e /ordemservicokanban). Escolha Módulo = Operação, deixe Exibir no menu em Sim e clique em Criar página.
6. ⚠️ O título da tela e o rótulo do menu não usam o nome que você digitou. Os dois nascem Kanban de status de os, derivados da tabela de etapas. Arrume nos dois lugares em que eles moram:
   • barra do editor → Propriedades da página → Título = Quadro de OS e, mais abaixo, Rótulo no menu = Quadro de OS; Fechar;
   • painel do meio → aba Árvore → page-header → Título = Quadro de OS.

   Clique em Salvar.

7. Selecione o nó kanban na Árvore. Em Fonte de dados, Database, Model (cards), Model (stages) e FK do stage aparecem travados, com a nota Definido na criação da página — não editável aqui. Para trocar, crie outra página.
8. Abra Coluna (stage). ⚠️ Atributo com o título, Atributo com a cor e Coluna de ordenação aparecem desabilitados, com o texto Configure model + database — ver *Erros comuns*. Você não precisa deles nesta aula: sem nada preenchido o quadro assume nome, cor e ordem na tabela de etapas, que é como a status_os foi montada na aula 03. Deixe Ordem em Ascendente.
9. Em Comportamento, confirme Drag & drop ligado e use Click no card → Escolher página → OrdemServicoForm (OrdemServicoForm) para o cartão abrir a OS da aula 09.
10. Selecione o Card do Kanban (nó kanban-card). Em Título, escolha numero — é um combo de atributo: ele lista as colunas de ordem_servico e as de tabelas relacionadas.
11. Ainda em Conteúdo, clique em Editor visual com preview logo abaixo de Meta do card. O modal Configurar meta do card abre com o cartão montado à direita, e tudo que você muda aparece nele na hora. Adicione:
    • Bloco com Path / template cliente->nome_razao_social;
    • Inline (chip) com Path / template tecnico->nome;
    • Bloco com Path / template valor_total e, em Formatação, Tipo = Moeda — só então aparecem Prefixo (R$ ) e Casas decimais (2).

    Cada linha da lista tem Remover e Duplicar; arrastar reordena. Feche em Fechar.

12. Logo abaixo, Badges do card tem o mesmo par: os atalhos #ID, Estado e Texto na *edição rápida* e o Editor visual com preview para o modal Configurar badges do card. O cartão já nasce com #ID e Estado; declarar qualquer badge próprio desliga os dois automáticos — o próprio modal avisa isso.
13. Em Comportamento, Ações do card oferece Inline (rodapé), Menu (três pontinhos) e Dropdown (botão único). Cada ação guarda o seu próprio *placement*.
14. Na barra do editor, clique no ícone Configurar filtros do Kanban (só aparece em página do tipo Kanban). No modal Filtros do Kanban, escolha Estilo = Toolbar e preencha Título (opcional) com Filtros.
15. Em Filtros declarados, clique em Adicionar filtro duas vezes. Em cada linha, escolha o tipo DB Combo e dê o nome do *bind*: tecnico_id e cliente_id. O rodapé do modal explica o que cada um vira no controller: public string $X = '' no bloco @mad-block:kanban-filter-props.
16. Em Regras de filtro, clique em + Adicionar Regra de Filtro. Abre o construtor Regras de filtro — OrdemServico (é ali, e não no modal de filtros, que mora a chave Auto-vincular com filtros declarados). Clique em Regra, escolha Coluna = tecnico_id e Valor = tecnico_id; o Preview do PHP gerado mostra o when(...) que vai para o controller. Clique em Aplicar. A lista passa a mostrar OrdemServico · 1 regra — WHERE tecnico_id = :tecnico_id.
17. Fechar, Salvar e, no rail, Teste online → Testar agora para o app receber a tela nova.
18. No app, entre em Operação → Quadro de OS. As seis colunas aparecem na ordem de status_os.ordem, com o ponto colorido de status_os.cor e a contagem ao lado do nome. Arraste um cartão de Aberta para Agendada e reabra a OS no formulário para confirmar que o status mudou.

Erros comuns

Checklist de encerramento

• A página Quadro de OS existe no módulo Operação e abre pelo menu do app.
• O menu e o cabeçalho dizem Quadro de OS (não Kanban de status de os).
• O quadro mostra seis colunas, na ordem de status_os.ordem e com a cor de status_os.cor.
• O cartão mostra número, cliente, valor_total em moeda e o técnico como chip.
• A barra de filtros aparece no topo com Tecnico_id e Cliente_id.
• Regras de filtro mostra OrdemServico · 1 regra.
• Arrastar um cartão de Aberta para Agendada muda o status ao reabrir a OS.
• Página salva (Salvar) e Teste Online republicado (Testar agora).

← Aula 12 — Consulta de OS + assinatura, scanner e imagem · Aula 14 — Calendário de visitas →

Objetivo

Transformar as datas de agendamento da OS numa agenda visual, em que a equipe vê a semana inteira, abre o chamado com um clique e remarca a visita arrastando o evento.

O que você terá no fim

• Página Agenda de visitas (tipo Calendário) no módulo Operação, visível no menu do app.
• Eventos lidos de ordem_servico, começando em dt_agendada e terminando em dt_prevista.
• Título do evento com número da OS e cliente, e a cor do evento vinda do status.
• Jornada de 08:00 às 18:00, sem fim de semana, com slot de 1 hora.
• Clique no evento abrindo o formulário de OS e arraste gravando a nova data — conferido no Teste Online.

Studio › + › Nova página › Calendário

Studio › Agenda de visitas › Visualização › Configurar visualização

App › Operação › Agenda de visitas

Passo a passo

1. Na tira do Studio, clique em + → Nova página e escolha Calendário (Agenda visual de eventos).
2. O Calendário não tem variações: o clique no tipo já leva ao passo Configuração (Passo 3 de 3; o trilho mostra Variação · Não aplicável).
3. Deixe Base de dados no banco do projeto (assistec) e escolha ordem_servico em Tabela.
4. Em Coluna com a data/hora inicial do agendamento, escolha dt_agendada (timestamp). O combo só oferece colunas de data, data/hora ou timestamp — a dica ao lado conta quantas existem (9 coluna(s)); se a tabela não tiver nenhuma, a dica vira nenhuma coluna date/datetime/timestamp.
5. Em Coluna com a data/hora final do agendamento, escolha dt_prevista (timestamp). As duas são obrigatórias — o botão Criar página só acende com as duas preenchidas.
6. Preencha Nome do item de menu com Agenda de visitas, Classe de controle com AgendaVisitasMad, Route com /agenda-visitas e Módulo com Operação. Deixe Exibir no menu em Sim e clique em Criar página.
7. ⚠️ Como no Kanban, o rótulo do menu e o título da tela nascem derivados da tabela (Calendário de ordem de serviços). Arrume nos dois lugares: Propriedades da página → Título e Rótulo no menu = Agenda de visitas; e, na Árvore, page-header → Título. Salvar.
8. Selecione o nó calendar na Árvore. Em Fonte de dados, Database, Model, Data/hora inicial e Data/hora final aparecem travados, com a nota Definido na criação da página — não editável aqui. Para trocar, crie outra página.
9. Campo título aceita um atributo só — ou uma máscara com vários. A máscara não sai da lista: clique no botãozinho Múltiplos atributos / máscara ao lado do combo, escreva {numero} — {cliente->nome_razao_social} na caixa Máscara e clique em Aplicar. (Clicar nos atributos da lista de baixo também anexa cada um à máscara.)
10. Em Campo cor, escolha {statusOs->cor} — a mesma coluna cor que a aula 03 cadastrou em status_os. ⚠️ Repare no nome: a lista mostra a relação do model (statusOs), não a tabela (status_os). Tabela de nome composto vira relação em camelCase, e é assim que ela aparece aqui. Cada evento passa a sair na cor do status em que a OS está.
11. Campo ID aparece desabilitado com Configure model + database (mesma limitação do Kanban) e não precisa de você: o padrão é id. Deixe Campo all-day vazio — as visitas têm hora marcada.
12. Abra Visualização. View padrão já vem agendaWeek (a semana com as horas do dia); month mostra o mês inteiro e listWeek, a semana em lista.
13. Clique em Configurar visualização. Em Horário, coloque Início 08:00 e Fim 18:00 — a jornada comercial da assistência. O que você escolher aqui vira time-range="08:00-18:00" no Blade da página.
14. Ainda na janela, em Duração do slot clique em 1 hora (são quatro atalhos — 15 min, 30 min, 1 hora, 2 horas — mais um campo de hora livre ao lado). Em Dias da semana, ligue Sem fim de semana: os sete botões de dia ficam esmaecidos, porque o atalho manda neles. Confirme Locale = Português (Brasil) e Fechar.
15. Abra a aba EVENTOS do painel (ao lado de PROPRIEDADES). Em Clique no evento, deixe Escolher página marcado e selecione OrdemServicoForm (OrdemServicoForm). Em Modo de abertura, escolha drawer (gaveta lateral) ou modal. Se quiser uma pergunta antes de gravar o arraste, preencha Texto confirm() com Remarcar esta visita?.
16. Ainda em EVENTOS, Clique em dia vazio aponta o formulário de OS: quem clica num horário livre abre uma OS nova já com aquela data, que chega como {date}.
17. Volte a PROPRIEDADES, abra Edição e ligue Drag & resize. Auto-update no drag já vem ligado — é ele que grava a data nova ao soltar o evento.
18. Abra Popover e preencha Popover título (máscara, igual ao passo 9) com {numero} — {cliente->nome_razao_social} e Popover conteúdo com descricao_problema. Em Gatilho, hover mostra a espiada ao passar o mouse; click exige um clique.
19. Em Apresentação, deixe Altura (px) vazio ou ligue Ocupa altura total para a agenda ocupar a tela.
20. Na barra do editor, clique em Configurar filtros do Calendário. Escolha Estilo = Toolbar, Título (opcional) = Filtros e, em Filtros declarados, Adicionar filtro duas vezes, com tipo DB Combo e os nomes tecnico_id e cliente_id. Em Regras de filtro, + Adicionar Regra de Filtro abre o construtor (é lá que mora Auto-vincular com filtros declarados).
21. Clique em Salvar. No rail, abra Teste online e clique em Testar agora.
22. No app, entre em Operação → Agenda de visitas. A semana aparece de segunda a sexta, das 08h às 18h, com os eventos escritos número — cliente. Clique num evento: o formulário da OS abre. Arraste outro para o dia seguinte e reabra a OS para confirmar que dt_agendada mudou.

Erros comuns

Checklist de encerramento

• A página Agenda de visitas existe no módulo Operação e abre pelo menu do app.
• O menu e o cabeçalho dizem Agenda de visitas.
• Os eventos vêm de ordem_servico, começando em dt_agendada e terminando em dt_prevista.
• Cada evento mostra número da OS e cliente no título.
• A agenda abre na semana, das 08:00 às 18:00, sem sábado e domingo.
• Clicar num evento abre o formulário da OS, e clicar num horário livre abre uma OS nova.
• Passar o mouse num evento mostra o popover com o problema.
• Arrastar um evento para outro dia grava a nova dt_agendada.
• A barra de filtros aparece no topo com Tecnico_id e Cliente_id.
• Página salva (Salvar) e Teste Online republicado (Testar agora).

← Aula 13 — Kanban de OS · Aula 15 — Dashboard operacional →

Objetivo

Montar a tela de abertura do sistema: quatro números-resumo, gráficos por status, por mês e por técnico, e uma barra de filtros no topo que recalcula tudo de uma vez.

O que você terá no fim

• Página Painel da operação (tipo Dashboard) no módulo Relatórios, visível no menu do app.
• Grade desenhada no designer de layout: uma linha de quatro cartões e três linhas de blocos.
• Quatro KPI Card — OS abertas (com regra de carregamento cortando as concluídas e as canceladas), horas trabalhadas, ticket médio e faturamento.
• Um Bar Chart por status, um Line Chart por mês, um Donut Chart por técnico, uma Pivot Table e uma Grid (listagem).
• Barra de filtros com período e cliente, e cada bloco dizendo a quais filtros obedece.
• Clique numa barra do gráfico de status filtrando o painel inteiro.

Studio › Painel da operação › Configurar layout

Studio › Painel da operação › Visual › KPI Card

Studio › Painel da operação › Visual › Bar Chart

Studio › Painel da operação › Configurar filtros do dashboard

Studio › Painel da operação › Visual › Bar Chart › Drill-down

App › Painel da operação

Passo a passo

1. Na tira do Studio, clique em + → Nova página e escolha Dashboard (KPIs, gráficos e indicadores). Como os outros tipos sem variação, o clique já leva ao passo Configuração.
2. Não há combo de tabela — o dashboard não pede nenhuma. Preencha Nome do item de menu com Painel da operação, Classe de controle com PainelOperacaoDashboard, Route com /painel-operacao e Módulo com Relatórios. Clique em Criar página. (Aqui o rótulo do menu e o título saem certos — o desvio do Kanban e do Calendário não acontece porque não há tabela de onde derivar nome.)
3. A tela nasce com o bloco de filtros no topo e a grade vazia. Na barra do editor, clique em Configurar layout (linhas + colunas de widgets).
4. Na janela Layout do Dashboard, clique em Adicionar linha e monte:
   • Linha 1 — Cols 4, Modo Uniforme; as quatro células em KPI Card;
   • Linha 2 — Cols 2, Modo Uniforme; Bar Chart e Line Chart;
   • Linha 3 — Cols 2, Modo Customizado, Larguras (%) 60 e 40 (há presets prontos: 50 / 50, 70 / 30, 20 / 60 / 20…); Donut Chart e Pivot Table;
   • Linha 4 — Cols 1, Modo Uniforme; Grid (listagem) — a lista de apoio embaixo do painel. Ela precisa de dois ajustes que os outros widgets não pedem (passo 14).
5. Clique em Aplicar layout. Célula que mantém o tipo mantém a configuração — aparece o aviso props preservadas nela.
6. Selecione o primeiro KPI Card pela Árvore (db-metric-card). Em Fonte de dados: Database já vem no banco do projeto; escolha Tabela (Model) = ordem_servico e Agregação = Contar (contar não pede campo numérico).
7. Em Estilo, preencha Label com OS abertas e Cor do cartão com Informação. Em Identificação, Nome (ID) = os_abertas — ele precisa ser único na página. ⚠️ Preencha o Nome (ID) por último: digitar nele redesenha o painel e o próximo combo que você clicar não abre.
8. Corte o cartão para o que o rótulo promete. Do jeito que está, ele conta todas as OS: o número é 40, o mesmo total da tabela, e o rótulo "OS abertas" passa a mentir. Abra Regras de carregamento (a seção fica acima de PROPRIEDADES) → Configurar filtros → Regra:
   • Coluna = status_os_id;
   • Operador = not in (a lista tem =, !=, <>, >, <, >=, <=, like, ilike, not like, not ilike, in, not in, is, is not);
   • Valor = 5,6 — os dois status que a aula 03 cadastrou com e_final = true: Concluída (5) e Cancelada (6).

   O Preview do PHP gerado confirma na hora:

   $filter_os_abertas = $that->baseQuery('OrdemServico')->whereNotIn('status_os_id', [5, 6]);

   Clique em Aplicar. O cartão passa a mostrar 29 no app — e o rótulo volta a ser verdade. A seção fica com o selo 1 filtro · 1 regra (AND).

   Regra de carregamento × barra de filtros.A regra é do cartão e a pessoa não desliga — é a definição de "aberta". A barra de filtros do passo 15 é do painel inteiro e recorta o período. O grupo Filtros do dashboard (logo abaixo, com Todos / Somente / Exceto / Nenhum) decide quais filtros da barra este cartão obedece; deixe em Todos.
9. Repita nos outros três cartões (sem regra de carregamento — eles medem o período inteiro):
   • horas_mes — Agregação Somar, Campo numérico horas_trabalhadas, Label Horas trabalhadas;
   • ticket_medio — Agregação Média, Campo numérico valor_total, Label Ticket médio;
   • faturamento — Agregação Somar, Campo numérico valor_total, Label Faturamento.

   Nos dois últimos, clique em Formato do campo numérico, busque R$ e escolha Moeda — R$ (R$ 1.234,50).

10. Selecione o Bar Chart. Em Fonte de dados, Tabela (Model) = ordem_servico, Agrupar por = {statusOs->nome}, Agregação = Contar. Em Identificação, Título = OS por status e Nome (ID) = os_por_status. ⚠️ Agrupar pela FK (status_os_id) também funciona, mas aí o eixo do gráfico sai com os números dos status. A lista mostra a chain pelo nome da relação do model — {statusOs->nome}, camelCase — e não pelo nome da tabela (status_os).
11. Selecione o Line Chart: Agrupar por = dt_abertura, Título = OS por mês, Nome (ID) = os_por_mes. Para o eixo mostrar o mês e não o instante, clique na chave ao lado do combo (Aplicar máscara SQL (ex: agrupar por mês)), escolha o banco (SQLite é o que o Teste Online usa) e o preset Mês (AAAA-MM); o rodapé mostra o SQL FINAL (strftime('%Y-%m', dt_abertura)). Aplicar.
12. Selecione o Donut Chart: Agrupar por = {tecnico->nome}, Título = OS por técnico, Nome (ID) = os_por_tecnico. Em Apresentação, Mostrar legenda já vem ligado.
13. Selecione a Pivot Table. A fonte de dados dela é própria e usa outro tipo de combo (abre um painel flutuante com busca): escolha Base de dados = assistec e Tabela = ordem_servico, e dê o Título Serviços por técnico e mês. ⚠️ Não pule este passo: sem tabela o bloco sai :query="$that->baseQuery()" no código e a página inteira para de abrir (*Erros comuns*). Em Configurar Campos e Visões você monta linhas, colunas e medidas da tabela dinâmica.
14. Grid (listagem) — selecione o nó grid na Árvore. Ele não tem *Agrupar por*: em Fonte de dados ele tem o campo Tabela, com Database e Model (escolha assistec e ordem_servico (OrdemServico)). Num dashboard não existe "tabela da página" — sem isso a página inteira para de abrir, igual à Pivot. Depois abra Colunas: ela começa em COLUNAS (0) / *Nenhum colunas configurado*. Clique + Add uma vez por coluna e preencha Campo e Label: numero (Nº), titulo (Título), dt_abertura (Abertura) e valor_total (Valor). ⚠️ Os filtros de período do dashboard não chegam a esta listagem (o próprio campo avisa) — use a Ordenação padrão e os filtros de coluna.
15. Na barra do editor, clique em Configurar filtros do dashboard. Escolha Estilo = Toolbar, Título (opcional) = Filtros e, em Filtros declarados, Adicionar filtro duas vezes:
    • a primeira linha em Período mês/ano — ela não tem campo de nome, porque reserva os binds $mes e $ano;
    • a segunda em DB Combo, com o nome cliente_id.

    Em Critério base ficam as regras fixas que valem para todos os blocos (Nenhuma regra declarada. enquanto não houver).

16. De volta ao canvas, cada bloco tem no topo do painel a faixa Filtros do dashboard: Todos obedece a tudo, Somente é lista branca, Exceto é lista negra e Nenhum ignora a barra. Deixe tudo em Todos.
17. Selecione o Bar Chart e abra a seção Drill-down (ela fica acima de PROPRIEDADES). Clique em Habilitar filtro ao clicar — o texto ao lado da chavinha também liga.
18. Em Modo, escolha Direto (FK simples): o clique manda o próprio valor da categoria para uma propriedade pública. Em Propriedade alvo, escreva status_os_id; o painel mostra que ela é Auto-declarada como public string $status_os_id = ''; no controller. Ligue Re-click na mesma categoria limpa o filtro.
    Os outros modos: Lookup (label → ID) quando o gráfico agrupa pelo NOME e o filtro precisa do código (pede Modelo — dois combos, Database + Model — e Campo de match); Período (mes/ano) quando o clique deve mexer no período do painel.
19. Clique em Salvar. No rail, abra Teste online e Testar agora.
20. No app, abra Painel da operação. Escolha o mês na barra, clique em Atualizar e veja os blocos recalcularem; clique numa barra do gráfico de status para filtrar o painel inteiro.

Erros comuns

Checklist de encerramento

• A página Painel da operação existe no módulo Relatórios e abre no app.
• A grade tem quatro linhas: 4 cartões, 2 gráficos, donut + pivot em 60/40 e a listagem de apoio.
• Os quatro cartões mostram número, horas, ticket médio e faturamento — os dois últimos em moeda.
• O cartão OS abertas tem 1 filtro · 1 regra (AND) e mostra 29 no app (não 40): a regra status_os_id not in 5,6 está gravada.
• O Bar Chart mostra a contagem por status (com o nome no eixo, não o código) e o Donut, por técnico.
• A listagem de apoio mostra as colunas Nº, Título, Abertura e Valor.
• A barra de filtros tem o período (mês/ano) e o combo de cliente.
• Clicar numa barra filtra o painel; clicar de novo limpa.
• Nenhum bloco aparece em vermelho no app.
• Página salva (Salvar) e Teste Online republicado (Testar agora).

← Aula 14 — Calendário de visitas · Aula 16 — Relatório de faturamento + PDF timbrado →

Objetivo

Montar o relatório que o financeiro leva para a reunião: faturamento quebrado por cliente e por mês, com sub-totais, e exportado em PDF com o timbre da empresa.

O que você terá no fim

• Página Faturamento por cliente (tipo Relatório) no módulo Relatórios.
• Duas quebras: cliente no primeiro nível, mês de abertura no segundo.
• Filtro de período por dt_abertura e filtros de técnico e de status.
• Três colunas somadas — serviços, peças e total — com sub-total por grupo e total geral.
• Uma segunda linha descritiva abaixo de cada OS, com número e problema.
• Cabeçalho e rodapé do PDF montados no editor de bandas, com título, subtítulo, período, filtros e paginação.

Studio › + › Nova página › Relatório

Studio › + › Nova página › Relatório

Studio › Faturamento por cliente › Visual › Grid

Studio › Faturamento por cliente › Propriedades da página › Exportação PDF

App › Faturamento por cliente › Exportar › PDF

Passo a passo

1. Na tira do Studio, clique em + → Nova página e escolha Relatório (Agrupamentos, subtotais e export PDF/Excel). Como os outros tipos sem variação, o clique já leva ao passo Configuração.
2. No passo Configuração, escolha Base de dados e, em Tabela, ordem_servico.
3. Em Agrupar por (nível 1), escolha cliente_id. Como é uma chave estrangeira, o assistente abre um segundo combo, Coluna de cliente, com o hint agrupa pelo valor da tabela relacionada. Escolha nome_razao_social. Deixar em Usar o código (ID) faria o relatório quebrar pelo número interno do cliente.
4. Em Agrupar por (nível 2), escolha dt_abertura. Como é uma data, aparece Granularidade da data, com Dia já escolhido. Troque para Mês — é isso que junta todas as OS do mesmo mês num grupo só.
5. Deixe Agrupar por (nível 3) em Sem agrupamento. Dois níveis já dão a leitura que o financeiro precisa.
6. Em Campo de período, escolha dt_abertura. É o campo que vira o filtro de datas na tela e alimenta o {PERIOD} do cabeçalho do PDF. Sem ele, o hint fica Sem filtro de período.
7. Em Filtros de dimensão (hint FKs que viram combos de filtro), marque tecnico_id e status_os_id.
8. ⚠️ Colunas totalizadas já vem marcada: o assistente pré-seleciona TODA coluna decimal da tabela (horas_trabalhadas, valor_servicos, valor_pecas, valor_deslocamento, valor_total). Desmarque o que não entra no faturamento e deixe só valor_servicos, valor_pecas e valor_total. Em Função de cada total, confirme Soma — é o padrão.
9. Deixe Saldo acumulado — crédito em Sem saldo acumulado. O saldo corrente serve a relatórios de caixa; este é de faturamento.
10. Em Linha descritiva (hint opcional — segunda linha abaixo de cada registro), clique no botãozinho Múltiplos atributos / máscara ao lado do combo, escreva {numero} — {descricao_problema} na caixa Máscara e clique em Aplicar (clicar nos atributos da lista de baixo também anexa cada um).
11. Preencha Nome do item de menu com Faturamento por cliente, Classe de controle com FaturamentoClienteMad, Route com /faturamento-cliente e Módulo com Relatórios. Clique em Criar página. ⚠️ Como nas aulas 13 e 14, o título da tela e o rótulo do menu nascem derivados da tabela (Relatório de ordem de serviços) — e aqui há um terceiro lugar: a migalha (Relatórios > Relatório de ordem de serviços). Ajuste em Propriedades da página (Título e Rótulo no menu) e, na Árvore, no nó page-header (Título e Breadcrumb).
12. Selecione a grade pela Árvore (nó grid). Abra a seção Agrupamento do painel.
13. Em Níveis de agrupamento, confira Nível 1 e Nível 2. Cada nível tem Agrupar por, Texto do cabeçalho (opcional) — a máscara da faixa do grupo — e, quando o campo é data, Separar datas por. Use Subir e Descer para trocar a ordem e Adicionar nível para incluir mais uma quebra.
14. Confirme Subtotais por grupo ligado. Em Banda do grupo, troque Linha única (padrão) por Alinhada às colunas: os valores do sub-total passam a sair embaixo da coluna correspondente, como num relatório impresso.
15. Em Rótulo do sub-total, escreva Sub-total do cliente. O campo aceita {group} para repetir o nome do grupo; vazio usa o padrão do tema.
16. Ainda em Agrupamento, confira Linha descritiva e preencha Título da exportação com Faturamento por cliente e Subtítulo da exportação com {PERIOD}. São eles que alimentam o {TITLE} e o {SUBTITLE} das bandas do PDF.
17. Na seção Paginação, coloque Itens por página em 0. Relatório agrupado não pagina: um grupo partido entre páginas não fecha o sub-total.
18. Abra a engrenagem Propriedades da página e desça até a seção Exportação PDF (ela só existe em listagem e relatorio); clique em Configurar cabeçalho e rodapé…. A janela Cabeçalho e rodapé do PDF abre com a folha ao centro, o CABEÇALHO em cima e o RODAPÉ embaixo, e dois seletores no topo: Cabeçalho do PDF e Rodapé do PDF, ambos em Padrão do projeto enquanto a página herdar.
19. Clique no cartão Modelos prontos (canto superior esquerdo, Comece com um layout pronto): abre a galeria com sete layouts — Corporativo clássico, Minimalista, Timbrado completo, Faixa azul, Navy executivo, Relatório financeiro e Confidencial, cada um com miniatura e o botão Usar este modelo. Escolha Relatório financeiro: ele traz título, subtítulo, período e filtros no cabeçalho e o total de registros no rodapé, e os dois seletores passam a Personalizado.
20. Ajuste o que faltar arrastando de ELEMENTOS: Texto, Logo / imagem, Nº de página, Data e Campo dinâmico. Em CAMPOS DISPONÍVEIS ficam os chips — {TITLE}, {SUBTITLE}, {DATE}, {PERIOD}, {FILTERS}, {TOTAL_REGISTER}, {APP_NAME}, {TENANT_NAME}, {UNIT_NAME} e {USER_NAME}.
21. Use Ímã e Grade para alinhar, e os campos altura, respiro e Fundo colorido para ajustar cada banda. As setas do teclado movem o elemento selecionado em passos finos.
22. Enquanto não houver campo próprio, a coluna CAMPOS DO PROJETO da janela de bandas fica em *Nenhum campo próprio no projeto* — é o estado do print desta aula. Para imprimir o CNPJ da empresa sem escrever código, abra Propriedades do projeto → Exportação de PDF → Campos próprios. Preencha Nome do campo com CNPJ e Valor com 00.000.000/0000-00 e clique em Adicionar. O campo vira um chip no editor de bandas. Repita com RAZAO_SOCIAL = Assistec Manutenção Exemplo Ltda.
23. Volte ao editor de bandas, arraste os chips {RAZAO_SOCIAL} e {CNPJ} para o cabeçalho e feche em Fechar. Precisa de um valor calculado para todas as telas? O botão Criar classe de campos, na mesma seção, gera a classe já com exemplos.
24. Clique em Salvar. No rail, abra Teste online e clique em Testar agora.
25. No app, abra Faturamento por cliente e deixe a leitura apresentável antes de mostrar (ou exportar):
    • em Status Os, escolha Concluída e clique em Atualizar — faturamento é o que fechou; o chip passa a marcar 1 filtro;
    • clique em Escolher colunas (o ícone de duas colunas, ao lado do de exportar) e deixe só Numero, Cliente, Tecnico, Dt Conclusao, Valor Servicos, Valor Pecas e Valor Total.

    ⚠️ Sem esse segundo passo o relatório parece quebrado. A grade do relatório é <mad-grid self>: ela nasce com todas as 25 colunas de ordem_servico, a tabela fica três vezes mais larga que a tela e as três colunas de valor caem para fora — as faixas SUB-TOTAL DO CLIENTE aparecem vazias mesmo com os números calculados corretamente.

    Agora confira as quebras Cliente: … e Mês: …, a linha descritiva abaixo de cada OS e os sub-totais alinhados sob as colunas de valor. Exportar é o ícone de download no canto superior direito da tabela (o rótulo só aparece no tooltip), com as opções Excel e PDF.

26. Os dois guias da Ajuda aprofundam esta aula: Relatório analítico com saldo acumulado (quando o relatório precisa de saldo corrente) e Cabeçalho e rodapé do PDF (o editor de bandas por inteiro). A própria janela do PDF tem o botão Ajuda.

Erros comuns

Checklist de encerramento

• A página Faturamento por cliente existe no módulo Relatórios e abre pelo menu do app.
• O relatório quebra por cliente (pelo nome, não pelo código) e, dentro dele, por mês.
• O filtro de período por dt_abertura aparece na tela, junto dos combos de técnico e status.
• Serviços, peças e total somam por grupo e no total geral.
• Cada OS mostra a segunda linha com número e descrição do problema.
• Banda do grupo está em Alinhada às colunas e o sub-total tem rótulo próprio.
• Itens por página está em 0.
• A janela Cabeçalho e rodapé do PDF está com o modelo aplicado e os dois seletores em Personalizado.
• Exportar oferece Excel e PDF. (O arquivo em si é a única coisa da aula que não aparece em print: abra o PDF e confira o timbre à mão antes de gravar.)
• Página salva (Salvar) e Teste Online republicado (Testar agora).

← Aula 15 — Dashboard operacional · Aula 17 — Planilha de apontamento de horas →

Objetivo

Criar a tela em que o técnico lança várias horas de uma vez — digitando na grade ou colando direto do Excel — e o sistema grava tudo numa única operação.

O que você terá no fim

• Página Apontamento de horas (tipo Planilha de lançamento) sobre os_apontamento.
• Sete colunas configuradas, com tipo, obrigatoriedade e largura definidos por coluna.
• Quinze linhas em branco ao abrir e rodapé de totais somando as horas.
• Um lote colado do Excel gravado no app, com a validação reprovando o lote inteiro quando alguma linha está incompleta.

Studio › + › Nova página › Planilha de lançamento

Studio › Apontamento de horas › Colunas da planilha

App › Operação › Apontamento de horas

App › Operação › Apontamento de horas

Passo a passo

1. Na tira do Studio, clique em + → Nova página e escolha Planilha de lançamento. Como o Kanban e o Calendário, ela não tem variações: o clique no tipo já leva ao passo Configuração (o trilho da esquerda mostra Variação · Não aplicável, e o rodapé, Passo 3 de 3).
2. No passo Configuração, escolha Base de dados e, em Tabela, os_apontamento.
3. Em Colunas da planilha (hint clique para incluir/remover), deixe marcadas as sete colunas que a pessoa digita: ordem_servico_id, tecnico_id, dt_referencia, tipo, horas, valor_hora e descricao_atividade. A chave e as colunas de controle não são oferecidas — e aqui, ao contrário das Colunas totalizadas do relatório, a lista já vem toda marcada, então é só desmarcar o que sobra.
4. Troque Linhas iniciais (hint padrão 10) para 15.
5. Preencha Nome do item de menu com Apontamento de horas, Classe de controle com ApontamentoHorasMad, Route com /apontamento-horas e Módulo com Operação. Clique em Criar página.
6. No canvas, selecione a planilha. Em Fonte de dados, Database e Model aparecem travados, com a nota Definido na criação da página — não editável aqui. Para trocar, crie outra página.
7. Clique em Colunas da planilha. A janela abre com o aviso Ordem da lista = ordem visual da grade. Tipo, obrigatoriedade, totais e combos por coluna.
8. ⚠️ Mexa nos Tipo ANTES dos rótulos. Trocar o tipo para Número ou Dinheiro faz nascer o campo Decimais na linha, e tudo que vem depois anda uma casa — quem preenche na ordem "linha a linha" acaba escrevendo o rótulo de uma linha dentro da Largura da anterior. Depois use Mover para cima e Mover para baixo (as setas ▲▼ à esquerda do número da linha) para deixar nesta ordem: ordem_servico_id, tecnico_id, dt_referencia, tipo, horas, valor_hora, descricao_atividade.
9. Ajuste linha a linha:
   • Rótulo: OS, Técnico, Data, Tipo, Horas, Valor/hora, Atividade.
   • Tipo: Combo nas duas primeiras, Data em dt_referencia, Texto em tipo e descricao_atividade, Número em horas, Dinheiro em valor_hora.
   • Obrigatória (o botão alterna entre Opcional e Obrigatória) em ordem_servico_id, tecnico_id e dt_referencia — são as três que a validação vai cobrar. As demais ficam em Opcional.
   • Largura maior em descricao_atividade; Decimais 2 em horas e valor_hora.
   • No campo Σ, escolha Soma para horas e para valor_hora.
10. Nas colunas de combo, clique em Abrir propriedades da coluna (o ícone de controles à direita da linha). Na seção Dados, configure o Datasource (tabela e coluna exibida) e, se a lista for grande, ligue Busca no servidor. Sem isso a coluna avisa configure a fonte do combo em Propriedades.
11. Feche a janela. Com a planilha selecionada, abra a seção Grade e confirme Linhas iniciais = 15, Máx. linhas por lote no padrão e Linha de totais (Σ) ligado.
12. Clique em Salvar. No rail, abra Teste online e clique em Testar agora.
13. No app, entre em Operação → Apontamento de horas. A grade abre com as 15 linhas em branco, um contador de linhas preenchidas no meio da barra e os botões +10 linhas, Desfazer, Validar e Salvar.
14. Copie este bloco de uma planilha (uma coluna por tabulação) e cole com Ctrl+V com o cursor na coluna Data da primeira linha — a colagem começa na célula onde o cursor está, não na linha de baixo:

    05/09/2026	execucao	3,5	90,00	Diagnóstico da câmara fria
    05/09/2026	execucao	2,0	90,00	Troca do termostato
    06/09/2026	execucao	4,0	90,00	Recarga de gás e teste de estanqueidade

15. Confira o rodapé: o Σ passa a mostrar 9,50 em Horas e 270,00 em Valor/hora, e o contador vira 3 linha(s) preenchida(s). As três linhas coladas trouxeram data, tipo, horas, valor e atividade de uma vez; OS e Técnico continuam vazias.
16. Clique em Salvar antes de completar as linhas: nada é gravado e o app avisa 6 erro(s) de validação — corrija as células destacadas, com as células obrigatórias em vermelho (três linhas × duas colunas). É a gravação em lote se protegendo — ou entra tudo, ou não entra nada. Preencha OS e Técnico nas três linhas e salve de novo; agora as três entram juntas. (Validar faz a mesma conferência sem gravar.)

Erros comuns

Checklist de encerramento

• A página Apontamento de horas existe no módulo Operação e abre pelo menu do app.
• A grade abre com 15 linhas em branco e as sete colunas na ordem definida.
• As colunas de OS e técnico abrem a lista de registros (combo configurado).
• O rodapé Σ soma as horas enquanto a pessoa digita.
• Um bloco colado do Excel entra de uma vez na grade.
• Salvar com uma linha incompleta não grava nada e aponta a linha.
• Página salva (Salvar) e Teste Online republicado (Testar agora).

← Aula 16 — Relatório de faturamento + PDF timbrado · Aula 18 — Gantt + Formulário de Gantt →

Objetivo

Montar o cronograma das ordens de serviço — cada OS vira uma barra no tempo, com subtarefas e percentual concluído — e criar o formulário que abre quando você clica numa barra.

O que você terá no fim

• Página Cronograma de OS (tipo Gantt, classe CronogramaOsMad) no módulo Operação, visível no menu do app.
• Barras montadas a partir de dt_inicio e dt_fim, com hierarquia por os_pai_id.
• Sidebar do cronograma com as colunas Tarefa, Início, Fim e Dias.
• Página Tarefa do cronograma (tipo Formulário de Gantt, classe CronogramaOsMadForm) vinculada ao Gantt e fora do menu.
• No app: clicar numa barra — ou no botão Nova — abre o formulário em gaveta.

Studio › + › Nova página › Gantt

Studio › + › Nova página › Formulário de Gantt

App › Operação › Cronograma de OS

App › Tarefa do cronograma

Passo a passo

Parte 1 — a página Gantt

1. No Explorer, clique em Nova página. No passo Tipo, grupo Operacional, escolha Gantt (descrição Cronograma de projeto — tarefas, fases e dependências).
2. O Gantt não tem variações: o clique no tipo já leva ao passo Configuração (o trilho da esquerda mostra Variação · Não aplicável, e o rodapé, Passo 3 de 3). Não há Continuar para clicar.
3. No passo Configuração, deixe Base de dados no banco do projeto e escolha Tabela = ordem_servico.
4. Preencha o mapeamento das colunas:
   • Coluna do nome da tarefa = titulo — é o texto escrito dentro da barra.
   • Coluna da data de início = dt_inicio — define onde a barra começa.
   • Coluna da data de fim = dt_fim — define a largura da barra. Enquanto o início estiver vazio, o campo fica com o aviso primeiro escolha o início.
   • Coluna pai (hierarquia) = os_pai_id. O hint explica: FK self-referente → tarefas/subtarefas. Opcional. Deixar em — Lista plana — dá um cronograma sem árvore.
   • Coluna de progresso = progresso. O hint é Numérica 0–100 (ou 0–1). Opcional.; a opção vazia é — Sem progresso —. ⚠️ Hoje esse combo não guarda a escolha: ele volta para — Sem progresso — por conta própria e o cronograma nasce sem a barra de preenchimento. O Gantt funciona sem ela (é opcional); para ter o preenchimento, aponte o campo Progresso depois, no modal Campos & colunas do canvas.
5. Preencha Nome do item de menu com Cronograma de OS, Classe de controle com CronogramaOsMad, Route com /cronograma-os e Módulo com Operação. Deixe Exibir no menu em Sim e clique em Criar página.

   ⚠️ Guarde o nome da classe. O cronograma gerado abre a gaveta de edição por um nome fixo, <classe do Gantt>Form — no nosso caso CronogramaOsMadForm. É esse nome que o formulário do passo 15 tem de ter.

6. No canvas, clique no cronograma para selecionar o <mad-gantt>. Na seção Fonte de dados, Database e Model aparecem travados, com a nota Definido na criação da página — não editável aqui. Para trocar, crie outra página.
7. Clique em Campos & colunas para abrir o modal Campos & colunas do Gantt. Cada linha é um campo que o Gantt entende:
   • Nome → texto da barra; Início e Fim → posição e largura;
   • Duração tem Origem calculada de início/fim — não existe coluna no banco;
   • Progresso e Pai (hierarquia) ficam em Só mapeia (alimentam o desenho, mas não viram coluna da lateral). É aqui que você aponta Progresso para a coluna progresso, já que o assistente não guardou a escolha do passo 4 — opcional, o cronograma funciona sem a barra de preenchimento;
   • Responsável, Código, Marco (milestone), Fase, Cor e Tipo ficam desligados neste curso — ligue com Incluir quando o modelo tiver a coluna.

   Para cada campo visível você ajusta Rótulo (cabeçalho) e Largura (px). A largura da lateral é a soma das colunas visíveis.

8. Clique em Dependências para abrir Dependências entre tarefas. Há três modos: Nenhuma (sem setas), Coluna FK (uma coluna da própria tarefa aponta o predecessor, sempre Finish→Start) e Tabela (uma tabela separada de arestas, com tipo e folga por linha). Nosso modelo tem só um auto-relacionamento, os_pai_id, e ele já é a hierarquia — então deixe em Nenhuma e feche. Setas entram quando você criar uma coluna os_predecessora_id ou uma tabela de dependências.
9. No grupo Tempo, escolha Zoom = Semana e deixe Locale em pt-br. Passo ao arrastar (min) em 1440 faz o arraste andar de dia em dia. ℹ️ Nota para quem grava: o print do app foi tirado no zoom Ano porque os dados de teste espalham dt_inicio/dt_fim por vários anos e, em Semana, quase nenhuma barra cai na janela visível. Com datas de verdade, Semana é o zoom certo.
10. No grupo Calendário, marque em Dias úteis de Seg a Sex e ajuste Horário de trabalho para o expediente da equipe. Fora dos dias úteis o cronograma não conta prazo.
11. No grupo Colunas & Visual, confira Mostrar fins de semana, Minimapa e Busca (⌘K) ligados, e escolha a Densidade.
12. Clique em Salvar.

Parte 2 — o Formulário de Gantt

1. Ainda no Explorer, clique em Nova página e escolha Formulário de Gantt (descrição CRUD de tarefa vinculado a um Gantt existente). Repare que este tipo não pede tabela: ele usa a tabela do Gantt.
2. No passo Configuração, abra Gantt vinculado e escolha Cronograma de OS. O hint conta quantos existem (1 Gantt disponível). Se você ainda não tivesse criado o Gantt, o combo viria vazio com o aviso nenhum Gantt no projeto — crie um Gantt primeiro — é por isso que a ordem desta aula é Gantt primeiro, formulário depois.
3. Preencha Nome do item de menu com Tarefa do cronograma. Em Classe de controle, não mude o que o assistente sugeriu: ao escolher o Gantt vinculado ele já escreveu CronogramaOsMadForm ali. Este nome importa — o Gantt do passo 5 abre a gaveta por <classe do Gantt>Form, e qualquer outro nome (por exemplo o OrdemServicoGanttForm derivado da tabela) deixa o clique na barra e o botão Nova abrindo uma classe que não existe. Deixe Exibir no menu em Não — o formulário é aberto pelo cronograma, não pelo menu. Clique em Criar página.
4. O formulário nasce com os campos que o Gantt usa, em três seções: Identificação (Nome da tarefa, titulo), Cronograma (Início, dt_inicio, e Fim, dt_fim — que já abrem preenchidos com hoje e hoje + 3 dias) e Hierarquia (Tarefa pai, os_pai_id, com a própria tarefa excluída da lista para não virar ciclo). Ajuste rótulos e larguras no canvas como em qualquer formulário e clique em Salvar.
5. No rail, abra Teste online e clique em Testar agora.
6. No app, entre em Operação → Cronograma de OS. Teste os três gestos:
   • arrastar uma barra muda dt_inicio/dt_fim;
   • clicar numa barra abre o formulário em gaveta;
   • o botão Nova, no cabeçalho do cronograma, abre o mesmo formulário em branco.

Erros comuns

Checklist de encerramento

• A página Cronograma de OS existe no módulo Operação e abre pelo menu do app.
• As barras respeitam dt_inicio e dt_fim.
• A lateral mostra Tarefa, Início, Fim e Dias (esta última calculada, sem coluna no banco).
• OS com os_pai_id preenchido aparece recuada sob a OS pai.
• A página Tarefa do cronograma existe com a classe CronogramaOsMadForm, está vinculada ao Gantt e não aparece no menu.
• Clicar numa barra abre o formulário; o botão Nova abre o formulário em branco.
• Arrastar uma barra grava as novas datas (confirmado ao reabrir a OS).
• Páginas salvas (Salvar) e Teste Online republicado (Testar agora).

← Aula 17 — Planilha de apontamento de horas · Aula 19 — Organograma da equipe + Timeline da OS →

Objetivo

Duas telas que mostram relação em vez de lista: o organograma desenha quem responde a quem na equipe técnica, e a timeline conta a história de uma OS na ordem em que aconteceu.

O que você terá no fim

• Página Organograma da equipe (tipo Organograma) lendo tecnico pela FK gerente_id.
• Cards com nome, cargo, foto (ou iniciais) e a capacidade diária como badge.
• No app: navegar com pan e zoom, buscar uma pessoa e arrastar um card para trocar de gerente.
• Página Histórico da OS (tipo Timeline) com o componente Timeline montado à mão.
• Linha do tempo lendo os_historico, com um marcador por evento na ordem configurada.

Studio › + › Nova página › Organograma

App › Cadastros › Organograma da equipe

Studio › Histórico da OS › Componentes

Studio › Histórico da OS › Visual › Timeline

App › Operação › Histórico da OS

Passo a passo

Parte 1 — Organograma da equipe

1. No Explorer, clique em Nova página. No passo Tipo, grupo Visualização, escolha Organograma (descrição Árvore hierárquica visual — cards com pan/zoom, busca, lazy e re-parent por drag).
2. O Organograma não tem variações: o clique no tipo já leva ao passo Configuração (o trilho da esquerda mostra Variação · Não aplicável, e o rodapé, Passo 3 de 3). Não há Continuar para clicar.
3. No passo Configuração, escolha Tabela = tecnico e preencha:
   • FK do pai (auto-referência) = gerente_id — hint coluna que aponta pra esta mesma tabela (ex.: parent_id). Quem tem essa coluna vazia é raiz da árvore.
   • Campo do título do card = nome.
   • Subtítulo (opcional) = cargo — hint cargo/código exibido sob o título.
   • Campo da foto (opcional) = foto — hint URL/path da imagem — vazio usa iniciais.
   • Métrica (opcional) = capacidade_hora_dia — hint numérico exibido como badge no card. A opção vazia é — nenhum —.
4. Preencha Nome do item de menu com Organograma da equipe, Classe de controle com TecnicoOrgChart, Route com /organograma-equipe e Módulo com Cadastros. Deixe Exibir no menu em Sim e clique em Criar página.
5. No canvas, selecione o organograma. No painel, grupo Card, preencha Rótulo da métrica com h/dia — é o texto que acompanha o número no badge.
6. Ainda no painel, grupo Comportamento:
   • Click no card aponta o formulário de técnico da aula 04 (TecnicoForm::onEdit({id}));
   • ligue Drag re-parent — arrastar um card sobre outro troca o gerente. O servidor recusa movimentos que criariam ciclo (alguém virar chefe do próprio chefe);
   • Níveis no load inicial em 0 traz a árvore inteira; num quadro grande, 2 carrega dois níveis e busca o resto conforme você expande.
7. Clique em Salvar e, no rail, Teste online → Testar agora.
8. Defina quem está no topo — a árvore não se monta sozinha. O organograma lê gerente_id: raiz é quem está com o gerente VAZIO, e todo o resto pendura debaixo de alguém. Antes de abrir a tela, no cadastro de técnicos:
   • abra o coordenador (o primeiro da lista) e deixe Gerente em branco;
   • abra outros três técnicos e ponha, em Gerente, o id do coordenador.

   ⚠️ Gerente é uma caixinha de número, não um combo. tecnico.gerente_id é Int sem chave estrangeira no modelo, e o gerador escolhe o campo pelo tipo da coluna: sai um campo numérico, onde você digita o id (1), não o nome. Se preferir escolher pelo nome, volte ao Modelos de dados e transforme gerente_id em FK de tecnico para tecnico — aí o CRUD nasce com um DB Combo mostrando o nome.

   Os dados de teste do Faker não preenchem gerente_id — sem esse passo você vê os técnicos lado a lado, numa fileira, sem nenhuma ligação.

9. No app, entre em Cadastros → Organograma da equipe. Carlos Andrade aparece no topo, com os três técnicos abaixo. Arraste a tela para navegar, use o zoom, busque por nome e arraste um card para trocar o gerente.

Parte 2 — Timeline da OS

1. No Explorer, clique em Nova página e escolha Timeline (grupo Visualização, descrição Linha do tempo de eventos). Repare: este tipo não pede tabela.
2. Preencha Nome do item de menu com Histórico da OS, Classe de controle com OsHistoricoTimeline, Route com /historico-os e Módulo com Operação. Clique em Criar página.
3. A página abre vazia, com apenas o cabeçalho. É assim mesmo: a Timeline é um componente, não um gerador — quem monta a tela é você.
4. Na busca da paleta de componentes (Buscar componente...), escreva Timeline: o grupo Interface fica com um único resultado. Arraste-o para dentro do conteúdo da página. Os grupos da paleta nascem recolhidos — por isso a busca é o caminho curto.
5. Com o componente selecionado, na seção Fonte de dados do painel (não é modal: os campos ficam ali mesmo):
   • Database = o banco do projeto (assistec) e Tabela (Model) = os_historico;
   • Chave = id;
   • Ordenar por = dt_evento, direção DESC — é ele que decide a ordem da linha do tempo;
   • Campo Título = titulo; Campo Corpo = observacao; Campo Data = dt_evento; Campo Ícone = icone; Campo Cor = cor;
   • Itens por página = 10. Limite total em branco (ou 0) traz tudo.

   Os cinco Campo … ficam gravados como nome de coluna puro (o componente lê $registro->{$campo}) e chegam assim ao app publicado: título, corpo e data aparecem corretamente. (O painel não mostra mais um "Campo de exibição" separado aqui — ele não tinha efeito nenhum na Timeline e foi retirado da seção.)

   Ícone e cor também chegam ao app pelo nome puro da coluna, mas só aparecem de verdade se o dado dessas colunas for um valor reconhecível: icone precisa do nome de um ícone do conjunto lucide (ex.: wrench, truck, check) e cor de uma cor CSS (ex.: blue, green, red) ou um hex. Os Seeds de dev (Faker) da aula 03 não sabem disso por padrão — sem escolher um Provider de lista fixa para essas duas colunas, icone/cor saem como texto aleatório (às vezes até uma URL de imagem) e o marcador aparece cinza, sem ícone (ver Erros comuns).

   Escolha o nome da coluna de título com carinho: é ele que a pessoa vai ler. Se os dados de teste da aula 03 preencheram titulo com nomes de pessoa (o Faker infere "nome" para um varchar chamado assim), troque o provider dessa coluna em Seeds de dev (Faker) antes de gravar — senão a linha do tempo vira uma lista de nomes.
6. No grupo Comportamento, ligue Itens como cards, Agrupar por data e Carregar mais. Dois lados (zigzag) distribui os itens à esquerda e à direita do trilho — bom para históricos longos, opcional aqui.
7. No grupo Formato, escolha Formato data/hora = d/m/Y H:i.
8. Clique em Salvar e depois Testar agora no Teste online. No app, Operação → Histórico da OS mostra a linha do tempo com um marcador por evento.
9. Extra (opcional) — a mesma peça dentro de outra tela. Abra a consulta de OS da aula 12, arraste outra Timeline para uma aba Histórico e repita a configuração do passo
   1. Depois abra Regras de carregamento: no modal, clique em Regra e monte

   Coluna ordem_servico_id · Operador = · Valor {id}. Clique em Aplicar. Assim a linha do tempo mostra só o histórico da OS aberta na tela.

Erros comuns

Checklist de encerramento

• A página Organograma da equipe existe no módulo Cadastros e abre pelo menu do app.
• A árvore mostra Carlos Andrade no topo e os três subordinados abaixo.
• O card mostra cargo como subtítulo e a capacidade diária como badge.
• Arrastar um card sobre outro troca o gerente (confirmado ao reabrir o cadastro).
• A página Histórico da OS existe no módulo Operação.
• A timeline está na página com Tabela (Model) = os_historico e os campos da linha do tempo preenchidos.
• No app, a linha do tempo mostra um marcador por evento de os_historico.
• Páginas salvas (Salvar) e Teste Online republicado (Testar agora).

← Aula 18 — Gantt + Formulário de Gantt · Aula 20 — Documento: impressão da OS em PDF →

Objetivo

Desenhar a ordem de serviço impressa — a folha que o técnico entrega e o cliente assina — e gerar o PDF direto do registro, sem escrever uma linha de código.

O que você terá no fim

• Página Impressão da OS (tipo Documento) ligada a ordem_servico.
• Folha A4 com cabeçalho e rodapé que se repetem em toda página.
• Dados da OS escritos como texto comum, com chips de variável no meio.
• Tabela de serviços vinda de os_servico_item, com total somado.
• QR Code e linha de assinatura no rodapé.
• PDF conferido pelo botão Testar PDF.

Studio › + › Nova página › Documento

Studio › Impressão da OS › Visual

Studio › Impressão da OS › Visual

Studio › Impressão da OS › Visual › Tabela

Studio › Impressão da OS › Testar PDF

Passo a passo

1. No Explorer, clique em Nova página. No passo Tipo, grupo Operacional, escolha Documento (descrição Ordem de serviço, NF, contrato).
2. O Documento não tem variações: o clique no tipo já leva ao passo Configuração (o trilho da esquerda mostra Variação · Não aplicável, e o rodapé, Passo 3 de 3). Não há Continuar para clicar.
3. No passo Configuração, escolha Tabela = ordem_servico. Preencha Nome do item de menu com Impressão da OS, Classe de controle com OrdemServicoDocument, Route com /impressao-os e Módulo com Operação. Deixe Exibir no menu em Não — o documento é chamado a partir da OS, não pelo menu. Clique em Criar página.
4. A página abre na aba Visual com o Editor de Documento: paleta Blocos do Documento à esquerda (grupos Conteúdo, Dados e Layout), a folha no meio e o painel à direita. A folha mostra três faixas: CABEÇALHO, o corpo e RODAPÉ, com a nota cabeçalho e rodapé se repetem no PDF.

   A paleta diz Arraste ou clique para adicionar: além de arrastar, clicar no bloco já o insere na folha. Onde esta aula disser "arraste", o clique também serve.

5. Sem nenhum bloco selecionado, o painel da direita é Configurações da página. Ajuste: Tamanho do papel A4, Orientação Retrato, Margens (mm) (Topo, Direita, Base, Esquerda), Fonte e Tamanho (pt). Em Cabeçalho defina Altura do cabeçalho (mm) e em Rodapé, Altura do rodapé (mm).
6. Opcional: clique em Templates para abrir a Galeria de templates (Escolha um modelo — você pode customizar tudo depois.). Aplicar um modelo pede confirmação (Substituir o documento atual?) porque troca todos os blocos — o Ctrl+Z desfaz.
7. Cabeçalho. Arraste Imagem (grupo Conteúdo) para a banda CABEÇALHO e preencha URL / data URI com a logo; ajuste Largura (mm) e Alinhamento. Ao lado, arraste um Título e escreva Assistec Manutenção Exemplo Ltda.
8. Identificação da OS. No corpo, arraste um Parágrafo. Escreva o texto fixo e, onde entra um dado da OS, digite $: um menu abre com os atributos de ordem_servico. Escolha e o valor vira um chip dentro do texto. Monte, por exemplo:

   OS {numero} · Aberta em {dt_abertura}
   Cliente: {cliente->nome_razao_social}
   Equipamento: {equipamento->nome}
   Técnico: {tecnico->nome}

   O que está entre chaves não é digitado: é o chip escolhido na lista do $. A lista abre com as colunas de ordem_servico (id, numero, titulo, cliente_id, equipamento_id, tecnico_id, tipo, prioridade, descricao_problema…) e rola para o resto. ℹ️ Nota para quem grava: confirme na sua lista se as colunas das tabelas relacionadas (cliente->nome_razao_social, tecnico->nome) aparecem; se não aparecerem, imprima o que existe na própria OS e deixe a chain fora da folha.

9. Formato dos valores. Clique num chip: o painel mostra Formatador. Escolha o formato de data para dt_abertura e o de moeda para valores. O Formatador não é um <select>: é uma lista agrupada com busca — Texto, Moeda, Número, Data e Hora, Documento BR e Personalizado. A aula 23 cria dois formatadores próprios e eles aparecem em Personalizado, no fim da lista.
10. Problema relatado. Arraste outro Parágrafo e insira o chip {descricao_problema}. Texto longo quebra sozinho na folha.
11. Tabela de serviços. Arraste Tabela de dados (grupo Dados). Ela entra na folha ainda vazia, com a faixa TABELA · SEM DETALHE · 1 COL — é o estado normal de quem acabou de inserir. Com o bloco selecionado, no painel:
    • aponte Tabela detalhe = os_servico_item (só entram tabelas que apontam para ordem_servico, marcadas com via FK);
    • escolha as colunas servico_id, quantidade, preco_unitario e subtotal. Alinhamento e formato já vêm sugeridos por tipo de coluna.

    O botão Assistente de colunas faz os dois passos de uma vez (escolhe a tabela detalhe — se ainda não escolhida — e as colunas), com os atalhos Todas (N), Nenhuma, Não-PK e Obrigatórias na seleção. ⚠️ Prefira o assistente para LIGAR o conteúdo da coluna; o editor livre de conteúdo (o ícone ao lado do campo, que abre uma caixa de texto com {atributo}) é ótimo para trocar só o rótulo depois, mas usá-lo para configurar o conteúdo do zero de uma tabela de dados pode deixar a célula em branco no PDF gerado por Testar PDF — vale conferir o PDF depois de montar a tabela por esse caminho.

12. Ainda no painel da tabela, ajuste por coluna: Rótulo da coluna, Largura, Alinhamento e Formato. Na coluna subtotal, ligue Totalizador = Soma. Em Estilo, ligue Zebra e ajuste Fonte (pt) e Cor do cabeçalho.
13. Peças. Repita o passo 11 com outra Tabela de dados apontando os_peca_item.
14. Totais. Arraste um Parágrafo alinhado à direita e insira os chips {valor_servicos}, {valor_pecas} e {valor_total}, cada um com Formatador de moeda.
15. Rodapé. Na banda RODAPÉ:
    • arraste QR Code e preencha Dados (URL ou texto) com um chip do número da OS; ajuste Tamanho (mm) e Correção de erro;
    • arraste Assinatura e preencha Nome e Cargo / papel (ex.: Cliente), ajustando Largura da linha (mm);
    • arraste Número de página (grupo Layout) — o formato padrão é Página {page} de {total}.
16. Clique em Salvar. ⚠️ Salve antes de trocar de aba: bloco inserido e não salvo some — o editor não guarda rascunho.
17. Clique em Testar PDF. O documento é gerado com um registro real da tabela e abre numa aba nova do navegador, no visualizador de PDF. O botão Preview, ao lado, mostra a renderização dentro do próprio editor.
18. Extra (opcional). Para chamar o documento a partir da OS, volte ao formulário da aula 09 e aponte um botão para esta página. Na aula 23 esse caminho é feito pelo Após salvar, que manda a OS recém-gravada direto para Impressão da OS · show.

Erros comuns

Checklist de encerramento

• A página Impressão da OS existe, é do tipo Documento e está ligada a ordem_servico.
• O papel está em A4, com margens e alturas de cabeçalho/rodapé definidas.
• O cabeçalho traz logo e nome da empresa e se repete em todas as páginas do PDF.
• Os dados da OS aparecem como chips escolhidos pelo $, não como texto fixo.
• Datas e valores têm Formatador aplicado.
• A tabela de serviços aponta Tabela detalhe = os_servico_item e soma subtotal.
• O rodapé tem QR Code, linha de assinatura e número de página.
• Documento salvo (Salvar) e Testar PDF abrindo o arquivo numa aba nova, sem erro.