docs: Decision 012 — Fase C com Bitrix24 como fonte da verdade comercial by adm01-debug · Pull Request #149 · adm01-debug/Promo_Gifts

adm01-debug · 2026-05-12T12:59:21Z

🎯 Objetivo

Registrar formalmente a decisão do sponsor (Joaquim, 12/05/2026) sobre o novo modelo de orçamento após a remoção das rotas públicas com token (Decisions 010+011).

Bitrix24 será a fonte da verdade comercial. Promo gera o orçamento (PDF/documento), Bitrix24 decide se virou venda.

📦 Decisões documentadas

1. Arquitetura: Híbrida (webhook real-time + reconciliação diária)

2. Status: manter vocabulário atual (`approved`/`rejected`/`pending_approval`)

Bitrix24 só "carimba" esses status via webhook/pull
Zero migração de dados históricos
Zero refactor dos 26 lugares dashboard/kanban/BI
validate_status_fields CHECK fica intacto

3. Sub-fases planejadas

Fase	Objetivo	Tempo
C.1	Validar pipe Promo→Bitrix em 4 camadas	1-2 dias
C.2	Reconciliação diária (cron pull)	2-3 dias
C.3	Webhook receiver (push)	2-3 dias
C.4	UI/indicadores + import catálogo	1-2 dias

🔍 Achado durante prep da C.1

O fluxo real depende de 4 secrets, não 1:

BITRIX24_WEBHOOK_URL (edge bitrix-sync direta)
N8N_QUOTE_WEBHOOK_URL (edge sync-quote-bitrix via n8n)
EXTERNAL_CRM_URL + EXTERNAL_CRM_SERVICE_ROLE_KEY (CRM externo para resolver bitrix_company_id)

Em PROD nenhum está cadastrado — herança do recovery do Lovable, que pegou só Cloudflare/XBZ.

🪜 Plano em camadas para Fase C.1

Camada	Valida	Pré-req	Quem executa
1	Bitrix24 alcançável	BITRIX24_WEBHOOK_URL	Sponsor (UI Testar)
2	Promo→n8n	N8N_QUOTE_WEBHOOK_URL	Claude (mock payload)
3	Promo→Bitrix direto	Camada 1 OK	Claude (bitrix-sync get_companies)
4	Quote end-to-end	bitrix_product_id + bitrix_company_id	depois de C.4

Camadas 1-3 dão pra validar HOJE com 2 secrets que o sponsor já tem.

⚠️ Nesta PR

Apenas documentação — zero código, zero secrets, zero DDL.

recovery/agent-db/DECISIONS.md → Decision 012 (180+ linhas, completa com complemento descoberto)
recovery/agent-db/progress.md → Fase C adicionada ao roadmap

✅ Validações

ESLint baseline: 1535 ≤ 1547 ✅
Zero mudança runtime

🤖 Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

Documentation
- Adicionada documentação da Fase C com estratégia de integração Bitrix24 como fonte de verdade comercial
- Documentado plano de sincronização híbrido (push + reconciliação) e critérios de validação para implementação das futuras fases de integração

Documenta arquitetura definida pelo sponsor em 12/05/2026 para o novo modelo de orçamento (sem rotas públicas com token). ## Decisões registradas ### Arquitetura: Híbrida (push real-time + reconciliação) - Promo→Bitrix: já existe (sync-quote-bitrix via n8n + bitrix-sync direto) - Bitrix→Promo: a construir nas Fases C.2 (pull diário) e C.3 (webhook) ### Status: manter vocabulário atual - Bitrix24 "carimba" approved/rejected via webhook ou pull - Zero migração de dados históricos - Zero refactor dos 26 lugares dashboard/kanban/BI - validate_status_fields CHECK fica intacto ### Sub-fases planejadas - C.1: validar pipe Promo→Bitrix em 4 camadas - C.2: reconciliação diária (cron pull) - C.3: webhook receiver (push) - C.4: UI/indicadores + import de catálogo ## Complemento descoberto durante prep da C.1 O fluxo real depende de 4 secrets (não 1): - BITRIX24_WEBHOOK_URL (edge bitrix-sync direta) - N8N_QUOTE_WEBHOOK_URL (edge sync-quote-bitrix via n8n) - EXTERNAL_CRM_URL + EXTERNAL_CRM_SERVICE_ROLE_KEY (CRM externo p/ bitrix_company_id) Em PROD nenhum está cadastrado — toda integração desligada após recovery. ## Plano em camadas para Fase C.1 | Camada | Valida | Pré-requisito | |---|---|---| | 1 | Bitrix24 alcançável | BITRIX24_WEBHOOK_URL colada | | 2 | Promo→n8n | N8N_QUOTE_WEBHOOK_URL colada | | 3 | Promo→Bitrix direto | Camada 1 OK | | 4 | Quote end-to-end real | Produtos com bitrix_product_id + company com bitrix_id (depende de C.4 e CRM externo) | Camadas 1-3 validáveis HOJE com os 2 secrets que sponsor tem em mãos. Camada 4 fica para a Fase C.4 (depende de dados, não infra). Próxima ação: sponsor cola 2 secrets via /admin/conexoes, então Claude executa testes de fumaça das camadas 1-3. Refs: Decisions 010, 011 (rotas públicas removidas)

vercel · 2026-05-12T12:59:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
promo-gifts	Building	Preview, Comment	May 12, 2026 0:59am

coderabbitai · 2026-05-12T12:59:37Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7e3f107b-f195-40ed-a29d-0ea07e81f727

📥 Commits

Reviewing files that changed from the base of the PR and between 0997cb1 and f35a13a.

📒 Files selected for processing (2)

recovery/agent-db/DECISIONS.md
recovery/agent-db/progress.md

Walkthrough

PR adiciona Decision 012 documentando a Fase C (Bitrix24 como fonte de verdade comercial) com arquitetura híbrida push+reconciliação pull, mapeamento de status preservando vocabulary existente, roadmap futuro em 4 fases, riscos/mitigações, e plano de validação técnica em 4 camadas com próximas ações de desbloqueio.

Changes

Decision 012 — Bitrix24 como Fonte da Verdade Comercial (Fase C)

Layer / File(s)	Summary
Decision 012 — Definição e Fase C.1 `recovery/agent-db/DECISIONS.md`, `recovery/agent-db/progress.md`	Arquitetura híbrida push+pull para sincronização Promo→Bitrix; mapeamento de `quotes.status` baseado em stages Bitrix (Won→`approved`, Lost→`rejected`); preservação explícita do status vocabulary sem cleanup histórico; Fase C.1 com tarefas concretas do sponsor (configurar `BITRIX24_WEBHOOK_URL`, sincronizar 1 quote, validar deal no Bitrix) e critério "Done" para sincronização fim-a-fim.
Roadmap futuro (C.2–C.4) e Riscos `recovery/agent-db/DECISIONS.md`	Planejamento das Fases C.2 (pull diário), C.3 (webhook receiver push), C.4 (UI/indicadores); KPIs/SLAs para monitoramento; riscos identificados: `SELLER_EMAIL_MAP` hardcoded, webhook sem retry nativo; mitigações: reconciliação diária, validação em 4 camadas.
Arquitetura Técnica e Desbloqueio `recovery/agent-db/DECISIONS.md`	Fluxo real Promo→Bitrix detalhado (CRM externo, PDF generation, n8n, edge); secrets necessários (`BITRIX24_WEBHOOK_URL`, `N8N_QUOTE_WEBHOOK_URL`, `EXTERNAL_CRM_URL`, `EXTERNAL_CRM_SERVICE_ROLE_KEY`) e estado atual no PROD (não cadastrados); plano de validação em 4 camadas; próxima ação objetiva: colar 2 secrets via `/admin/conexoes` para destravar camadas 1–3.

Estimated Code Review Effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly Related PRs

adm01-debug/Promo_Gifts#143: Introduz Decision 012 no mesmo arquivo recovery/agent-db/DECISIONS.md — mudanças documentam o planejamento da integração Bitrix24 em paralelo.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/decision-012-fase-c-bitrix-source-of-truth

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

Documenta a Decision 012 para a Fase C (novo modelo de orçamento) estabelecendo o Bitrix24 como fonte da verdade comercial, após a remoção das rotas públicas com token (Decisions 010+011). Também atualiza o roadmap do recovery para incluir a execução planejada da Fase C e a descoberta operacional sobre dependência de secrets.

Changes:

Adiciona a Decision 012 detalhando arquitetura híbrida (push + reconciliação diária), mapeamento de status e plano em camadas (C.1–C.4).
Registra a descoberta de que o fluxo real depende de 4 secrets (Bitrix, n8n e CRM externo) e o estado atual em PROD.
Atualiza o progress.md com a seção da Fase C e seus próximos passos.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
recovery/agent-db/progress.md	Adiciona a Fase C ao roadmap, com status e subfases C.1–C.4.
recovery/agent-db/DECISIONS.md	Inclui a Decision 012 com contexto, arquitetura, mapeamentos, riscos e plano de execução.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+| Deal stage = qualquer outro (Em negociação, etc) | `quotes.status` não muda automaticamente |
+
+**Implicação importante:** **não há cleanup de status** a fazer.
+- `validate_status_fields` CHECK fica intacto (ainda aceita approved/rejected/pending_approval/viewed)


+Status: **manter vocabulário atual** (`approved`/`rejected`/etc), Bitrix24 só "carimba" eles.  
+Não há cleanup de status histórico (decisão do sponsor 12/05).


Copilot AI review requested due to automatic review settings May 12, 2026 12:59

adm01-debug merged commit 9c4c09f into main May 12, 2026
11 of 14 checks passed

Copilot started reviewing on behalf of adm01-debug May 12, 2026 13:00 View session

vercel Bot deployed to Preview May 12, 2026 13:00 View deployment

Copilot AI reviewed May 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Decision 012 — Fase C com Bitrix24 como fonte da verdade comercial#149

docs: Decision 012 — Fase C com Bitrix24 como fonte da verdade comercial#149
adm01-debug merged 1 commit into
mainfrom
docs/decision-012-fase-c-bitrix-source-of-truth

adm01-debug commented May 12, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented May 12, 2026

Uh oh!

Uh oh!

coderabbitai Bot commented May 12, 2026 •

edited

Loading

Review failed

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		Status: manter vocabulário atual (`approved`/`rejected`/etc), Bitrix24 só "carimba" eles.
		Não há cleanup de status histórico (decisão do sponsor 12/05).

Conversation

adm01-debug commented May 12, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Objetivo

📦 Decisões documentadas

1. Arquitetura: Híbrida (webhook real-time + reconciliação diária)

2. Status: manter vocabulário atual (approved/rejected/pending_approval)

3. Sub-fases planejadas

🔍 Achado durante prep da C.1

🪜 Plano em camadas para Fase C.1

⚠️ Nesta PR

✅ Validações

Summary by CodeRabbit

Uh oh!

vercel Bot commented May 12, 2026

Uh oh!

Uh oh!

coderabbitai Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Estimated Code Review Effort

Possibly Related PRs

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adm01-debug commented May 12, 2026 •

edited by coderabbitai Bot

Loading

2. Status: manter vocabulário atual (`approved`/`rejected`/`pending_approval`)

coderabbitai Bot commented May 12, 2026 •

edited

Loading