# 🏢 Office AI Blueprint

> Um modelo reproduzível para construir um **cérebro operacional** para um escritório de serviços
> profissionais: um servidor que conecta todas as suas ferramentas (CRM, financeiro, atendimento,
> agenda, automações), correlaciona os dados por uma **chave única**, expõe tudo num **painel
> gerencial** e oferece um **conector MCP** para que um assistente de IA (Claude) opere sobre os
> dados com segurança.

Este repositório é a **planta** (blueprint) — documentação + esqueleto de código rodável.
Ele foi extraído de um projeto real (anonimizado) e organizado para que **qualquer pessoa
consiga executar a mesma coisa do zero**.

---

## 🎯 O que você constrói seguindo este guia

```
                ┌─────────────────────────────────────────────┐
                │              Assistente de IA                │
                │           (Claude via conector MCP)          │
                └───────────────────────┬─────────────────────┘
                                        │  stdio / HTTP
                ┌───────────────────────▼─────────────────────┐
                │        Servidor do Escritório (FastAPI)      │
                │   ┌──────────┬──────────┬─────────────────┐  │
                │   │  Painel  │   MCP    │  Daemons/Cache  │  │
                │   └──────────┴──────────┴─────────────────┘  │
                └───────────────────────┬─────────────────────┘
                                        │
   ┌───────┬───────┬───────┬───────┬────┴───┬───────┬───────┬───────┬───────┐
   ▼       ▼       ▼       ▼       ▼        ▼       ▼       ▼       ▼       ▼
  CRM   Financ. Atend.  Assinat. Agenda  Automaç. Reuniões  Dev   Banco  Públ.
(tasks) (contas)(chat) (contratos)(cal.)  (n8n)   (notas) (git)  (SQL)  (APIs)
   └───────┴───────┴───────┴───────┴────────┴───────┴───────┴───────┴───────┘
                                        │
                          Correlação por CHAVE ÚNICA
                       (ex.: nº do processo / código do contrato)
                                        │
                                 Fonte única de verdade
                              (vault Markdown / wiki interna)
```

- **Servidor central** (FastAPI) que fala com 10+ APIs externas.
- **Conector MCP** que entrega ~50 ferramentas a um assistente de IA — **quase tudo só-leitura**,
  escrita liberada só onde é seguro e **auditada**.
- **Painel gerencial** web por áreas (comercial, financeiro, operacional, etc.).
- **Correlação de dados**: uma chave única costura informação espalhada em sistemas diferentes.
- **Automações** (n8n) para as esteiras repetitivas.
- **Base de conhecimento** em Markdown que é, ao mesmo tempo, a documentação humana **e** a
  memória do assistente de IA.

---

## 🚀 Começar (resumo)

```bash
# 1. Clone
git clone <seu-fork> office-blueprint && cd office-blueprint

# 2. Crie os ambientes e copie o template de variáveis
./scripts/setup.ps1          # Windows PowerShell
# (ou) bash scripts/setup.sh # Linux/Mac

# 3. Preencha suas chaves
cp .env.example .env         # depois edite .env com seus tokens

# 4. Suba o servidor + o MCP
./scripts/start.ps1
```

> ⚠️ **Nada funciona "magicamente de uma vez"**: cada integração exige a **sua** conta e a **sua**
> chave de API. O que este repo automatiza é todo o *esqueleto, a cola e o passo a passo*. O
> trabalho manual é só criar contas e colar tokens no `.env`. Veja
> [`docs/07-passo-a-passo.md`](docs/07-passo-a-passo.md).

---

## 📚 Documentação

| Doc | O que cobre |
|-----|-------------|
| [`ROADMAP.md`](ROADMAP.md) | As 4 fases de implantação, do controle à automação total |
| [`docs/01-arquitetura.md`](docs/01-arquitetura.md) | Como as peças se encaixam; decisões de design |
| [`docs/02-integracoes.md`](docs/02-integracoes.md) | As 11 integrações: auth, formato e armadilhas de cada API |
| [`docs/03-criar-mcp.md`](docs/03-criar-mcp.md) | Passo a passo para criar o conector MCP |
| [`docs/04-correlacionar-apis.md`](docs/04-correlacionar-apis.md) | A "espinha dorsal": como costurar dados de sistemas diferentes |
| [`docs/05-painel-automacoes.md`](docs/05-painel-automacoes.md) | O painel gerencial e as esteiras de automação |
| [`docs/06-seguranca.md`](docs/06-seguranca.md) | Regras inegociáveis de segurança e LGPD |
| [`docs/07-passo-a-passo.md`](docs/07-passo-a-passo.md) | Checklist executável do zero ao ar |

---

## ⚖️ Princípios

1. **Só-leitura por padrão.** Dados de cliente são sensíveis. Escrita só onde necessário e sempre logada.
2. **Fonte única de verdade.** Toda decisão vive num lugar só (a base de conhecimento Markdown).
3. **Faseado.** Mapear → organizar → automatizar. Nunca automatizar uma dor que você não entendeu.
4. **Segredo nenhum no Git.** `.env` e dados de cliente ficam de fora (veja [`.gitignore`](.gitignore)).

## 📄 Licença

MIT — veja [`LICENSE`](LICENSE). Use, adapte, comercialize. Sem garantias.