# Processo: homologação → main + manual para toda a empresa Este documento descreve um **fluxo manual** (passo a passo) para: 1. Trazer **todas** as alterações de `homologação` para a `main` (via `upstream`), com a `main` atualizada antes. 2. Resolver conflitos **sempre** seguindo [resolucao-conflitos.md](resolucao-conflitos.md). 3. Produzir um **manual para toda a empresa** em linguagem **simples** (como para atendimento/comercial), com **Antes / Depois** concretos, **temas agrupados** quando fizer sentido (ex.: CRM inteiro num só bloco) e **sem** seções extras de “resumo executivo” ou “checklist de QA” dentro desse manual. 4. **Não** enviar alterações para o remoto da `main` automaticamente: você revisa tudo localmente e só faz `push` quando decidir. Comandos e detalhes de merge também estão em [guia-merge-upstream-main-homologacao.md](guia-merge-upstream-main-homologacao.md). Use este arquivo como **roteiro único** do processo; use o outro como referência de comandos. --- ## Princípios obrigatórios | Regra | O que significa na prática | |--------|----------------------------| | **Main antes de homologação** | Sempre alinhar a `main` local com `upstream/main` **antes** de mergear `upstream/homologacao`. | | **Conflitos** | Toda resolução segue [resolucao-conflitos.md](resolucao-conflitos.md) (prioridade da `main` só quando incompatível; mesclar quando compatível; Form Request, logs, consistência). | | **Sem commit automático** | Nenhum `git commit` sem sua **confirmação explícita** (ou de quem conduz o processo). | | **Sem push automático na `main`** | Depois de puxar/mergear, **não** rode `git push` na `main` até você revisar: diff, testes que forem possíveis no ambiente, e os dois relatórios abaixo. | | **Dois entregáveis de texto** | Um para **desenvolvimento** (conflitos/decisões; checklist de QA **pode** ficar aqui) e outro para **toda a empresa** (linguagem simples, Antes/Depois, temas agrupados, **sem** código/arquivos e **sem** resumo executivo nem checklist de QA **nesse** manual). | --- ## Pré-requisitos - Working tree limpo ou alterações guardadas (`stash`). - Remote `upstream` apontando para o repositório oficial. - Leitura de [resolucao-conflitos.md](resolucao-conflitos.md) **antes** do merge de homologação. - Opcional e recomendado: [revisar_padronizacao.md](revisar_padronizacao.md). - Quando o merge tocar **autenticação, permissões (DaCruz/administrativo), webhooks, uploads, LGPD ou formulários públicos**: percorrer [revisar-seguranca-padroes-sistema.md](revisar-seguranca-padroes-sistema.md) na revisão local. --- ## Fase 1 — Preparar e alinhar a `main` 1. `git checkout main` 2. `git fetch upstream` 3. `git merge upstream/main` - Se houver conflito nesta etapa, resolva com o mesmo guia [resolucao-conflitos.md](resolucao-conflitos.md). - **Não** avance para a Fase 2 sem a `main` local refletir o que está em `upstream/main`. --- ## Fase 2 — Trazer homologação para a `main` local 1. `git merge upstream/homologacao` 2. Para cada conflito: - Abrir o arquivo, aplicar as regras de [resolucao-conflitos.md](resolucao-conflitos.md). - Remover **todos** os marcadores `<<<<<<<`, `=======`, `>>>>>>>`. 3. Conferir que não sobrou marcador (busca no projeto ou revisão por arquivo). **Ainda nesta fase:** não é obrigatório commitar. Você pode deixar tudo resolvido e staged apenas quando estiver satisfeito. --- ## Fase 3 — Verificações antes de “fechar” o merge (local) Ajuste à realidade do que mudou (controllers, JS, views, etc.): - Sintaxe PHP em arquivos críticos alterados (ex.: `php -l caminho/do/arquivo.php`). - Testes automatizados **se o ambiente tiver banco/credenciais** para isso; se falhar por ambiente, registre isso no relatório técnico em vez de ignorar silenciosamente. - `git status` e revisão do `git diff` (e `git diff --cached` após `git add`). - **Segurança:** se o diff afetar áreas sensíveis (login, sessão, permissões DaCruz ou administrativo, rotas em `routes/api.php`, webhooks, uploads, consentimento LGPD, validação de inputs), usar o checklist de [revisar-seguranca-padroes-sistema.md](revisar-seguranca-padroes-sistema.md) e registrar no relatório técnico (§4.1) qualquer risco residual ou exceção aceita. Esta fase é **obrigatória** mesmo quando não há commit automático: o objetivo é não propagar erro para a `main` remota depois do seu `push`. --- ## Fase 4 — Documentação (dois arquivos) ### 4.1 Relatório técnico de conflitos e decisões - **Público:** time técnico / quem mantém o repositório. - **Conteúdo:** decisões por arquivo, fusões, referência a regras do [resolucao-conflitos.md](resolucao-conflitos.md), impacto técnico; **pode** incluir checklist de validação para dev/QA **neste** arquivo (isso **não** vai no manual da empresa). - **Onde salvar:** por exemplo `docs/conflitos-resolvidos-YYYY-MM-DD.md` (modelo sugerido em [guia-merge-upstream-main-homologacao.md](guia-merge-upstream-main-homologacao.md)). ### 4.2 Manual para toda a empresa (comunicação ao time — padrão atual) - **Público:** empresa inteira (incluindo quem **não** é da área técnica). - **Onde salvar:** por exemplo `docs/resumo-completo-equipe-main-homologacao-YYYY-MM-DD.md` (ajuste à convenção da equipe). **Regras de conteúdo e tom (alinhado ao que o time passou a usar no manual de merge homologação → main)** 1. **Linguagem** — Explicar como quem conta para **atendimento, comercial ou financeiro**. Evitar jargão (sem frameworks, “API”, tipos de requisição, nomes de tabelas, “pipeline de deploy”, etc.). 2. **Proibido no corpo do manual** — Nomes de **arquivo**, **pasta**, **classe** ou trecho de **código**. Também **não** incluir, no final desse mesmo documento, seção de **“resumo executivo”** em bullets nem **“checklist de validação / QA”** (quem precisar de checklist usa o relatório técnico da §4.1 ou outro artefato fora do manual de divulgação à empresa). 3. **Cobertura** — Registrar **todas** as mudanças funcionais relevantes do merge, não só destaques. 4. **Seções** — Sugestão: **1) Site** · **2) Administrativo** · **3) DaCruz** · **4) Comunicação** (e-mails e mensagens automáticas) · **5) Operação** (o que roda sozinho no servidor, descrito em linguagem de negócio: lembretes, LGPD, rotinas de CRM quando houver, etc.). 5. **Antes / Depois** — Em cada assunto: - **Antes:** como funcionava **na prática** para quem usa (cliente no site, equipe no administrativo, transportadora no DaCruz). Se algo **não existia**, dizer claramente (**ex.:** “não havia CRM no administrativo”). - **Depois:** o que muda de forma **observável** (o que a pessoa **vê**, **recebe**, **clica** ou **deixa de fazer**). Evitar frases vagas (“alinhou à homologação”) sem dizer *o quê* mudou para o usuário. 6. **Agrupamento** — Tudo que pertence ao **mesmo tema** no mesmo release deve ficar **num único bloco** (ex.: **CRM administrativo** — telas centrais, origem/canal na transportadora, lista geral, logins, menu e permissões — **numa seção só**, com subtópicos numerados se precisar), em vez de repetir o tema em vários títulos soltos. 7. **Transparência** — Se o merge **não** altera uma área, uma frase curta no início da seção pode dizer que **não houve mudança** nesse pacote (evita texto genérico que parece mudança). 8. **Opcional** — Onde ajudar (ex.: manuais, integrações), um sub-bloco **“O que fazer na prática”** (quem testa, o que abrir após o deploy). > O manual da empresa **não** substitui o relatório de conflitos (§4.1): público e objetivo diferentes. --- ## Fase 5 — Commit (somente com confirmação explícita) 1. `git add` nos arquivos desejados (código + os dois `.md` ou o que a política do time exigir). 2. `git commit` **somente** depois de você revisar o diff e aprovar a mensagem de commit. Ninguém deve assumir commit automático neste processo. --- ## Fase 6 — Revisão final e push na `main` (deliberado) 1. Releia o **manual para a empresa** como se fosse **atendimento ou comercial**: cada mudança está em **Antes / Depois** compreensível? Tem **agrupamento** onde combinado (ex.: CRM)? **Não** há código nem seção de “resumo executivo” / checklist de QA nesse manual? 2. Confira se o **relatório técnico** (§4.1) cobre conflitos e decisões. 3. Só então: `git push` para o remoto da `main` (ou abra PR, conforme política do repositório). **Regra:** entre o fim do merge local e o `push`, deve existir um intervalo de **revisão humana** sua (ou do responsável). Não há “push automático após puxar homologação” neste processo. --- ## Checklist rápido (imprimível) - [ ] `main` local atualizada com `upstream/main` antes do merge de homologação. - [ ] Merge `upstream/homologacao` concluído sem marcadores de conflito. - [ ] Conflitos resolvidos conforme [resolucao-conflitos.md](resolucao-conflitos.md). - [ ] Verificações locais executadas (e limitações de ambiente anotadas se houver). - [ ] Revisão de segurança conforme escopo: [revisar-seguranca-padroes-sistema.md](revisar-seguranca-padroes-sistema.md) (quando o merge tocar autenticação, permissões, webhooks, uploads ou LGPD). - [ ] `docs/conflitos-resolvidos-YYYY-MM-DD.md` (ou equivalente) gerado. - [ ] Manual para **toda a empresa** gerado: Site / Administrativo / DaCruz / Comunicação / Operação; **Antes/Depois** concretos; **agrupamento** de temas relacionados (ex.: CRM); **sem** jargão técnico, **sem** código/arquivos, **sem** “resumo executivo” nem checklist de QA **no** manual da empresa. - [ ] Commit feito **após** confirmação explícita. - [ ] `push` na `main` **após** revisão final — nunca automático por este roteiro. --- ## Prompt curto para IA (merge assistido, sem push) Cole e adapte a data/nomes de arquivo: ```text Conduza até a revisão local: merge upstream/main na main local, depois merge upstream/homologacao, resolvendo conflitos com prompts_dev/resolucao-conflitos.md. Não faça git commit nem git push sem minha confirmação explícita. Ao final, gere: (1) docs/conflitos-resolvidos-YYYY-MM-DD.md para o time técnico; (2) docs/resumo-completo-equipe-main-homologacao-YYYY-MM-DD.md para toda a empresa — linguagem simples (atendimento/comercial), todas as mudanças funcionais, seções Site / Administrativo / DaCruz / Comunicação / Operação, cada assunto com Antes e Depois na prática do usuário, agrupar temas relacionados num único bloco (ex.: CRM administrativo inteiro), sem nomes de arquivo/código, sem jargão técnico, sem seção de resumo executivo nem checklist de QA no final desse manual. Mostre o plano em 5 passos antes de comandos. ``` --- ## Resultado esperado - `main` local contendo `upstream/main` + `upstream/homologacao`, com conflitos tratados de forma padronizada. - Dois documentos: **técnico** (§4.1, pode incluir checklist para dev) + **empresa** (§4.2: manual legível por qualquer setor, Antes/Depois, agrupado, sem resumo/checklist no final desse arquivo). - **Push** na `main` remota só quando você validar que está tudo revisado.