Playbook
As regras que todo projeto da IT.IA segue, do jeito que o banco se comporta até as etapas que nenhum projeto pode pular, mesmo com uma pessoa só no time.
As regras que o banco segue. Valem para todos os projetos e aplicações, sem exceção.
| Regra | Como funciona | Por quê |
|---|---|---|
| Um banco só | Single database para o sistema inteiro da IT.IA. Nenhum projeto ganha um Supabase separado. | Tudo conversa com tudo: o Overview, a busca e a IA enxergam todos os projetos sem juntar bancos diferentes. |
| Tabelas comuns com o código do projeto | Tarefas, frentes, comentários, tempo, pedidos e fichas ficam em tabelas únicas, e cada linha carrega o project_id. | Projeto novo não exige programação: é só um código novo, e board, calendário e painéis já funcionam. |
| Pasta própria para o exclusivo | O que só existe num projeto (as tabelas do sistema do BL, por exemplo) fica num Schema só daquele projeto. | Separa o que é particular sem soltar o projeto do resto. |
| Cada um vê só o que é seu | A RLS garante que o cliente só enxerga o próprio projeto e o dev só os projetos em que está. | A segurança fica no banco, não só na tela. Mesmo que uma tela erre, o dado não vaza. |
| Permissão explícita em toda tabela nova | Toda tabela nova recebe GRANT além da RLS. A RLS filtra linhas; o GRANT libera a operação. | Faltando um dos dois, a tela quebra, inclusive consultas de outras tabelas que dependem dela. |
| Fonte única da verdade | Cada informação existe uma vez só. Board, tabela, calendário e canvas são Views, e todas editam o mesmo registro. | Mudou num lugar, mudou em todos. Nunca existem duas versões da mesma tarefa. |
| Clientes cadastrados aqui | Todo cliente da IT.IA fica na tabela de Clients deste sistema, inclusive a Blanco & Lisboa, que entra como cliente do tipo holding. As empresas do grupo (YOU, Realizze, BEEC, Gestão de Lojas e Cobrança 40%) não são clientes: são produtos dentro do projeto BL, e o cliente é a Blanco & Lisboa. | A IT.IA atende clientes de dentro e de fora do grupo com a mesma estrutura, e o stakeholder de cada cliente vê só o que é dele. |
| Estrutura por ligação, não por etiqueta | Onde cada coisa mora (a holding do cliente, o projeto da aplicação) é uma Relationship. Ligação não se apaga, só se move. | Se alguém apagar ou renomear uma etiqueta, nada perde o lugar. |
| Etiquetas livres e automáticas | As Tags são criadas, editadas e apagadas à vontade. As System tags (Holding e Projeto) aparecem com cadeado e ninguém apaga. | Você vê tudo como etiqueta, e a estrutura continua protegida. |
| O ID nunca muda | Cada registro tem um ID e um Path. As ligações usam o ID; o caminho se refaz sozinho quando algo é movido. | Mover uma aplicação para outro projeto não quebra tarefas, comentários, tempo nem provas. |
| Product é opcional | Entre o projeto e a aplicação pode existir um Product. Projeto simples vai direto para a aplicação. | Serve tanto para um app sozinho quanto para um projeto como o BL, com várias empresas e vários apps. |
| Nunca apagar, arquivar | Excluir vira Soft delete. O registro sai da vista, mas continua no banco. | Dá para desfazer, auditar e recuperar histórico. |
| Tudo registrado | Toda mudança grava quem fez, quando, e o antes e o depois, no Audit log. | Responde "quem mudou isso?" sem depender de memória. |
| Mudança de estrutura só por migration | Criar ou alterar tabela, função ou regra sempre vira um arquivo de Migration, aplicado uma vez só e guardado no repositório. | A estrutura do banco fica reproduzível, e ninguém aplica a mesma mudança duas vezes. |
| Uma versão por função | Ao mudar uma função do banco, a versão antiga é substituída, nunca somada. Nada de Overload. | Duas versões juntas já causaram erros reais de "função não é única" no ERP. |
| Segredos fora do banco e do código | Senha, token e chave de API nunca ficam escritos. O sistema guarda só o nome e onde buscar, no Secrets catalog. | Um arquivo vazado não entrega acesso a nada. |
| Hora sempre certa | O banco grava em UTC e a tela mostra no horário de São Paulo. | Prazos e relatórios nunca ficam com 3 horas de diferença. |
| Evento repetido não duplica | Integrações e automações são Idempotent. | Um aviso que chega duas vezes não cria duas tarefas nem duas cobranças. |
| Produção é só leitura para agentes | Agentes de IA leem o banco de Production com permissão mínima. Qualquer escrita, publicação ou migração exige o "sim" do William. | O sistema em uso nunca é alterado por engano. |
| Memória dos agentes separada | O que os agentes aprendem fica no Agent Core, nunca no banco do produto. | Dado de cliente e anotação de IA nunca se misturam. |
| Dinheiro sempre com moeda e data | Todo valor guarda a moeda (real ou dólar) e a data. Custos em dólar usam o Exchange rate registrado, e cada proposta guarda a regra de cálculo que valia quando foi feita. | O custo e o preço de um mês antigo não mudam quando o câmbio ou uma regra muda hoje. |
| Salários protegidos | Salário, benefícios e custo de cada pessoa ficam numa tabela que só o Master enxerga. | O time trabalha com o custo hora médio sem ver o salário dos colegas. |
| Isolamento provado com dois clientes | Toda regra de acesso é testada com duas empresas de teste: uma não pode ver nada da outra. | Só teste com duas contas prova que o isolamento funciona. |
Todo projeto passa por estas Stage gates, na ordem da tabela. Cada etapa tem uma Lens responsável.
| Etapa | O que é | Lente | O que precisa ser cumprido | Entrega que libera a próxima |
|---|---|---|---|---|
| Intake | Entrada e triagem do pedido | Triagem |
| Ficha do pedido |
| Scoping | Recorte do que entra e do que não entra | Supervisor · Arquitetura e mapeamento |
| Escopo aprovado |
| Discovery | Levantamento do que existe e de quem usa | Investigação do legado · Produto |
| Dossiê atual e matriz de evidências |
| Design | Desenho da solução | Arquiteto · Banco de dados · Segurança · Impacto |
| Documento de arquitetura |
| Planning | Plano de execução | Supervisor · Dev líder · AI PO |
| Backlog priorizado |
| Build | Construção | Dev especialista |
| Código com testes passando |
| QA & Security | Testes e segurança | QA · Segurança · Auditoria técnica |
| Relatório de testes e segurança |
| Verification | Verificação final | Verificador final |
| Relatório de verificação |
| Approval | Aprovação do William | William |
| Aprovação registrada |
| Release | Entrega no ar | Dev líder · Impacto e regressão |
| Versão no ar |
| Retrospective | Aprendizado depois da entrega | Aprendizado e prevenção |
| Lições registradas |
Regras que valem para todas as etapas
| Situação | Como funciona |
|---|---|
| Time de uma pessoa só | Quem está sozinho no time veste todas as lentes, uma de cada vez. A etapa não some porque o time é pequeno. |
| Projeto do zero | Greenfield começa no Intake e passa por todas as etapas. |
| Projeto em andamento | Brownfield também começa no Intake. No Discovery, marca com evidência as etapas que já estão cumpridas. |
| Item que não se aplica | Vira Waiver, com o motivo e quem aprovou. Nada é pulado em silêncio. |
| Aviso ou trava | Por enquanto todos os itens só avisam. O Master escolhe, item por item, se aquele item avisa, trava ou fica desligado. |
| Prova do que foi feito | O Master pode exigir uma Evidence em qualquer item. Quem executa anexa a prova, e ela fica guardada no item para ser vista depois. |
Como cada item pode ser configurado pelo Master
| Configuração | Opções | O que acontece |
|---|---|---|
| Modo |
| Aviso deixa seguir e mostra o alerta. Trava só libera a próxima etapa quando o item estiver cumprido. Desligado não cobra o item naquele projeto. |
| Obrigatório |
| Item obrigatório aparece destacado para quem executa e entra no aviso ou na trava. |
| Tipo de prova |
| Quem executa precisa anexar a prova do tipo pedido para marcar o item como cumprido. |
| Quem pode cumprir |
| Só quem tem a permissão consegue marcar o item e anexar a prova. |
| Registro |
| Tudo fica gravado no item, e o Master consulta depois, a qualquer momento. |
| Onde vale |
| A regra pode valer para todo projeto novo ou ser ajustada só em um projeto ou numa aplicação. |
Do mais amplo para o mais detalhado. Dentro de qualquer projeto dá para criar produtos e aplicações novos, e qualquer um pode ser movido para outro lugar.
| Nível | O que é | Exemplo no projeto BL | Obrigatório |
|---|---|---|---|
| Client | Quem contrata. Pode ser holding, empresa ou pessoa. Empresa pode estar ligada a uma holding. | Blanco & Lisboa (holding) · YOU Contabilidade (ligada à holding BL) | Sim |
| Project | O trabalho contratado por um cliente. | BL | Sim |
| Product | Conjunto de aplicações de uma mesma unidade de negócio. Opcional. | Blanco & Lisboa · YOU Contabilidade · Realizze · BEEC · Gestão de Lojas · 40% | Opcional |
| Application | Cada sistema ou app entregue. Fica dentro de um produto ou direto no projeto. | Java BL · App celular do CEO · Java Fiscal · App Área do Cliente | Sim |
| Workstream | As trilhas dentro da aplicação. | Frontend · Backend · Database · Integrations · AI | Sim |
| Epic | Um bloco grande de trabalho. | Módulo Financeiro | Opcional |
| Story | O que a pessoa vai conseguir fazer. | O CEO vê o faturamento do mês | Opcional |
| Task | O trabalho do dia a dia. | Criar a tabela de faturamento | Sim |
| Sub-task | Um pedaço de uma tarefa. | Criar o índice da tabela | Opcional |
Etiquetas
| Tipo | Como funciona | Exemplo |
|---|---|---|
| System tag | Gerada pelas ligações. Aparece com cadeado, muda sozinha quando algo é movido e ninguém apaga. |
|
| Tag | Criada, editada e apagada à vontade. Pode ir em cliente, projeto, produto ou aplicação, com nome, cor, categoria e descrição. |
|
O Data model do banco do projeto, já no ar no Supabase e conferido com os dados desta tela. A coluna Quem vê é o que as regras de RLS aplicam de verdade.
| Tabela | O que guarda | Campos | Quem vê |
|---|---|---|---|
| Estrutura | |||
nos | A árvore inteira: cada cliente, projeto, produto, aplicação e frente é uma linha | pai id, nome, status, motivo pausa, ordem, criado por | Master e quem participa (e o caminho até a raiz) |
nos_ancestrais | Cada registro ligado a todos os que estão acima dele. Mantida pelo banco, deixa os painéis rápidos | ancestral id, no id, distancia | Igual à estrutura |
clientes | O que só o cliente tem: tipo (holding, empresa, pessoa), documento e a holding | no id, tipo cliente, documento, holding id | Igual à estrutura |
projetos | O que só o projeto tem: do zero ou em andamento, início e data alvo | no id, origem, inicio, alvo | Igual à estrutura |
aplicacoes | O que só a aplicação tem: plataforma, código nosso ou de terceiros e o serviço do Catalog | no id, plataforma, origem codigo, servico id | Igual à estrutura |
frentes | O que só a frente tem: o limite de cartões em andamento | no id, wip limite | Igual à estrutura |
etiquetas | As etiquetas livres | nome, cor, categoria, descricao | Todos; só o Master muda |
etiquetas_nos | Qual etiqueta está em qual registro da estrutura | etiqueta id, no id | Igual à estrutura |
| Pessoas e acesso | |||
pessoas | O time e os stakeholders, ligados ao login quando ele existir | auth user id, nome, email, funcao, habilidades, capacidade h, papel, ativo | Todos; só o Master muda |
participacoes | Quem participa de onde e com que papel (vale para tudo abaixo) | pessoa id, no id, papel | O Master e a própria pessoa |
| Trabalho | |||
status_fluxo | Os status: o padrão e os personalizados de cada nível, cada um num grupo do fluxo | no id, chave, nome, explicacao, cor, grupo, ordem | Todos; só o Master muda |
itens | Epics, stories, tarefas, subtarefas e bugs. Um registro só, lido por todas as views | frente id, pai id, titulo, descricao, status id, prioridade, responsavel id, relator id, estimativa h, pontos, inicio, prazo, data prevista, visivel cliente, sprint id, marco id, ordem, iniciado em, concluido em, arquivado em | Master e o time; o stakeholder só o visível ao cliente |
itens_ligacoes | Bloqueia, relacionado e duplica (guardado num sentido só) | origem id, destino id | Quem vê o registro de origem |
itens_checklist | As listas de conferência dos itens | item id, texto, feito, ordem | Quem vê o registro de origem |
campos_personalizados | Os campos personalizados criados num nível | no id, nome, opcoes, ordem | Master e o time de onde participa |
itens_campos | O valor de cada campo personalizado em cada item | item id, campo id, valor | Quem vê o registro de origem |
comentarios | Comentários num item ou direto num nível | item id, no id, autor id, texto, visivel cliente, editado em | Master e o time; o stakeholder só o visível ao cliente |
sprints | Os ciclos curtos de cada projeto, sem sobreposição | projeto id, nome, meta, inicio, fim, status | Master e o time de onde participa |
marcos | Os marcos e as entregas de versão | no id, nome, descricao, data, visivel cliente, entregue em | Master e o time; o stakeholder só o visível ao cliente |
tempo_registros | Cronômetro por item e tempo em foco na frente, na mesma tabela | pessoa id, origem, item id, frente id, inicio, fim, nota | A própria pessoa, o time e o Master |
blocos_agenda | Os horários reservados para um item, sem sobreposição | item id, pessoa id, inicio, fim | Master e o time de onde participa |
visoes_salvas | Os filtros e agrupamentos guardados com nome | pessoa id, no id, nome, visao, filtros, agrupamento, ordenacao, compartilhada | O dono, ou todos quando compartilhada |
automacoes | Quando acontecer algo, faça algo | no id, nome, gatilho, condicao, acao, parametros, ativa, criado por | Só o Master |
automacoes_execucoes | O registro de cada vez que uma automação rodou | automacao id, item id, resultado, detalhe, em | Só o Master |
notificacoes | Os avisos de cada pessoa | pessoa id, titulo, texto, item id, lida em | A própria pessoa |
quadros | O quadro visual (Whiteboard) de cada nível | no id | Master e o time de onde participa |
quadro_elementos | Cartões, textos, formas e setas do quadro, que podem apontar para registros de verdade | quadro id, x, y, largura, altura, texto, cor, ref no id, ref item id, de id, para id | Master e o time de onde participa |
| Ficha técnica e etapas | |||
ficha_campos | Os campos da ficha técnica; a aplicação herda do projeto o que não preencher | no id, secao, campo, valor, personalizado, atualizado por | Master e o time de onde participa |
decisoes | O registro de decisões de cada nível | no id, titulo, motivo, alternativas, decidido por, decidido em | Master e o time de onde participa |
segredos_catalogo | A lista de segredos: só o nome e onde fica, nunca o valor | no id, nome, onde fica, para que, quem acessa, ultima troca | Só o Master |
requisitos | Os requisitos mínimos obrigatórios | nome, descricao, padrao, ordem | Master e time |
etapas_modelo | As etapas obrigatórias do modelo padrão | chave, nome, explicacao, lente, entrega, ordem | Master e time |
etapas_modelo_itens | Os itens de cada etapa, com modo, prova e quem cumpre | etapa id, texto, modo, obrigatorio, prova tipo, quem cumpre, pessoa id, so terceiros, ordem | Master e time |
etapas_nos | A situação de cada item de etapa em cada projeto e aplicação, com os ajustes do Master | no id, item modelo id, modo, prova tipo, situacao, cumprido por, cumprido em, motivo dispensa | Master e o time de onde participa |
provas | As provas anexadas nos itens de etapa | no id, item modelo id, valor, enviado por, enviado em | Master e o time de onde participa |
| Comercial e custos | |||
servicos | O Catalog: cada serviço que a IT.IA vende | codigo, categoria, nome, descricao, entregaveis, frentes padrao, horas min, horas max, sla, checklist inicio, ativo | Master e time |
servicos_cobranca | Os modelos de cobrança de cada serviço | servico id, modelo, parametros, ordem | Só o Master |
servicos_requisitos | Quais requisitos valem para cada serviço | servico id, requisito id | Master e time |
regras_calculo | As regras de cálculo, com a data em que passam a valer | vigente desde, regime, aliq simples, aliq presumido, aliq real, inss patronal, rat, terceiros, fgts, ferias, terco ferias, decimo terceiro, multa fgts, horas mes, faturavel pct, margem pct, contingencia pct, folga rateio pct, manutencao pct, cambio usd, complexidade, urgencia, criado por | Só o Master |
pessoas_custos | O custo de cada pessoa por vínculo, com vigência | pessoa id, vinculo, salario, prolabore, valor pj, beneficios, vigente desde | Só o Master |
cambio | O câmbio de cada dia | moeda, dia, valor | Só o Master |
custos_operacao | Os custos da operação interna | nome, categoria, valor, moeda, recorrencia, meses depreciacao, inicio, fim | Só o Master |
custos_tecnicos | Os custos técnicos, ligados ao nível da estrutura (o cliente vem da árvore) | no id, fornecedor, categoria, descricao, recorrencia, moeda, valor, unidade, limite, plano, proximo plano, proximo valor, extra por unidade, repasse, taxa repasse pct, inicio, fim | Só o Master |
custos_uso | O uso de cada custo, mês a mês | custo id, mes, quantidade, valor pago | Só o Master |
receitas | O que cada cliente paga, ligado ao projeto ou à aplicação | no id, servico id, descricao, modelo, valor, moeda, forma, parcelas, inicio, fim | Só o Master |
| Service Desk e agentes | |||
slas | O prazo combinado por gravidade, em qualquer nível | no id, gravidade, horas resposta, horas solucao | Quem vê o nível |
pedidos | Os pedidos dos stakeholders, com o contexto capturado e o item gerado | no id, autor id, gravidade, status, titulo, contexto, item id, duplicado de, respondido em, resolvido em | O time e quem pediu |
pedidos_mensagens | A conversa de cada pedido: cliente, IA e equipe | pedido id, autor tipo, pessoa id, agente id, texto, transcricao | Quem vê o registro de origem |
agentes | Os agentes do Agent Studio | codigo, nome, papel, instrucoes, regras passagem, modelo ia, ativo | Master e time |
agentes_fontes | As fontes de conhecimento de cada agente | agente id, nome, ref | Master e time |
agentes_ferramentas | As ferramentas de cada agente e o nível de permissão | agente id, ferramenta, permissao | Master e time |
agentes_execucoes | O registro do que cada agente fez | agente id, pedido id, item id, ferramenta, entrada, saida, resultado, tokens, custo usd, em | Só o Master |
agentes_avaliacoes | Os testes que medem se o agente responde certo | agente id, pergunta, resposta esperada, ultima resposta, nota, avaliado em | Só o Master |
anexos | Arquivos e links, cada um preso a exatamente um lugar | nome, mime, tamanho bytes, storage path, url, no id, item id, comentario id, pedido id, mensagem id, prova id, decisao id, enviado por | Quem vê o registro de origem |
| Contas (BI) e registro | |||
bi.painel | O painel de qualquer nível: indicadores, progresso por parte, status, 14 dias, avisos, concluídos, mudanças e ritmo | Pela tela, conforme o papel | |
bi.financeiro | Custo do mês, já gasto, já cobrado, repasse, a receber, resultado e equipe para terminar, com a linha do tempo | Pela tela, conforme o papel | |
bi.parametros_preco e bi.calcular_preco | O preço da hora e a calculadora do Catalog | Pela tela, conforme o papel | |
bi.custo_pessoas e bi.operacao_mensal | O custo de cada pessoa pelo vínculo e a operação interna em valor mensal | Pela tela, conforme o papel | |
bi.custos_mensais e bi.receitas_mensais | Cada custo e cada receita mês a mês, desde o início (pode ser antigo) e com previsão | Pela tela, conforme o papel | |
bi.previsao_limites | Em quantos meses cada plano chega no limite | Pela tela, conforme o papel | |
bi.ritmo_semanal | Criados, concluídos, Lead time e Cycle time por semana, em cada nível (guardado pronto e atualizado a cada 10 minutos) | Pela tela, conforme o papel | |
bi.velocidade_sprints e bi.queima_sprint | A velocidade de cada ciclo e o gráfico de queima | Pela tela, conforme o papel | |
bi.carga | As horas de cada pessoa por dia, comparadas com a capacidade | Pela tela, conforme o papel | |
bi.pedidos_sla | A situação do prazo de cada pedido | Pela tela, conforme o papel | |
bi.etapas_situacao e bi.ficha_do_no | As etapas de cada projeto e a ficha técnica com herança | Pela tela, conforme o papel | |
auditoria.registros | Quem fez o quê, com o antes e o depois só do que mudou | Só o Master | |
O modelo da Tech sheet que todo projeto e toda aplicação têm. A aplicação Inherits da ficha do projeto e muda só o que for diferente.
| Seção | O que é | Campos |
|---|---|---|
| Identificação | Os dados básicos |
|
| Visual identity | Identidade visual |
|
| Stack | Conjunto de tecnologias usadas |
|
| Repositories | Onde fica guardado o código |
|
| Environments | Ambientes onde o sistema roda |
|
| Database | Banco de dados |
|
| APIs | Canais de conversa entre sistemas |
|
| Integrations | Ligações com outros sistemas |
|
| Secrets catalog | Lista de segredos, sem os valores |
|
| Business rules | Regras de negócio |
|
| Decisions | Decisões tomadas |
|
| Baseline requirements | Requisitos mínimos obrigatórios em todo sistema |
|
| Anexos e anotações | Arquivos e textos livres |
|
| Custom fields | Campos personalizados |
|
O Blueprint do Sistema IT.IA. Tracejado é o que já está desenhado mas depende de algo de fora para funcionar.
public passando pelas regras de acesso, e as contas saem do bi. Os gatilhos do banco escrevem a auditoria sozinhos, e a rotina agendada atualiza o ritmo a cada 10 minutos. O traço vermelho é a escrita de dados.