database-designer

Database Designer

Projete esquemas de banco de dados completos e prontos para produção com base nos requisitos do usuário. Gere documentação abrangente, scripts SQL e arquivos de diagrama ER visuais compatíveis com DrawDB.

Princípios Centrais de Design

Antes de iniciar qualquer design, sempre leia references/design-principles.md para entender:

• Sem chaves estrangeiras físicas (apenas relacionamentos lógicos)
• Tamanhos de campos realistas baseados no uso real
• Design de índices mínimo e estratégico
• Comentários obrigatórios em todas as tabelas e campos
• Campos padrão do sistema (id, timestamps, exclusão lógica)
• Convenções de nomenclatura snake_case

Fluxo de Trabalho

Etapa 1: Entender Requisitos

Colete informações sobre o design do banco de dados:

1. Tipo de banco de dados: MySQL 8.0 (padrão), PostgreSQL, SQL Server, etc.
2. Domínio de negócio: E-commerce, blog, CRM, ERP, etc.
3. Entidades principais: Quais são as principais tabelas necessárias?
4. Funcionalidades-chave: Qual funcionalidade o banco de dados deve suportar?
5. Requisitos especiais: Alguma restrição ou preferência específica?

Se o usuário fornecer informações mínimas, infira de forma inteligente os detalhes ausentes com base em cenários de negócios comuns e melhores práticas documentadas em references/design-examples.md.

Cenários-chave de inferência:

• Usuário diz "projete uma tabela de usuários" → Inferir: username, password, email, phone, status
• Usuário diz "sistema de e-commerce" → Inferir: tabelas user, product, order, order_detail
• Usuário diz "sistema de blog" → Inferir: tabelas user, article, comment, tag, article_tag

Etapa 2: Carregar Documentação de Referência

Com base nos requisitos de design, carregue as referências apropriadas:

• Sempre carregar: references/design-principles.md para regras centrais de design
• Para geração de formato: references/drawdb-formats.md para especificações JSON/DBML
• Para exemplos: references/design-examples.md para designs de sistemas similares

Etapa 3: Projetar Esquema de Banco de Dados

Crie estruturas de tabela completas seguindo estas diretrizes:

Checklist de Design de Tabela

Para cada tabela:

• ✅ Adicionar campos padrão do sistema (a menos que o usuário especifique o contrário):

  • id BIGINT AUTO_INCREMENT PRIMARY KEY
  • created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  • updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
  • is_deleted TINYINT(1) DEFAULT 0

• ✅ Projetar campos de negócio com tamanhos realistas:

  • username: VARCHAR(50)
  • email: VARCHAR(100)
  • phone: VARCHAR(20)
  • title: VARCHAR(200)
  • description: TEXT
  • Consulte references/design-principles.md para padrões completos de tamanho

• ✅ Adicionar restrições apropriadas:

  • NOT NULL para campos obrigatórios
  • Valores DEFAULT para campos opcionais
  • UNIQUE para campos que exigem unicidade (mas não como chaves estrangeiras)

• ✅ Adicionar COMMENT a cada tabela e campo

• ✅ NÃO crie restrições FOREIGN KEY físicas

Estratégia de Design de Índices

Para cada tabela, analise e crie índices para:

1. Campos da cláusula WHERE: Campos usados com frequência em filtros
2. Campos JOIN: Todos os campos xxx_id de chave estrangeira
3. Campos ORDER BY / GROUP BY: Campos de ordenação e agrupamento
4. Restrições únicas: email, phone, order_no, etc. → Índices UNIQUE

Convenções de nomenclatura de índices:

• Índice comum: idx_nome_campo ou idx_campo1_campo2
• Índice único: uk_nome_campo

Limites de índices:

• Máximo de 5 índices por tabela (a menos que o usuário solicite mais)
• Crie apenas índices que suportem diretamente consultas de negócio

Design de Relacionamentos

Identifique relacionamentos lógicos entre as tabelas:

1. Um-para-Muitos (1:N): Mais comum

   • Exemplo: user (1) → order (N)
   • Implementação: Adicionar user_id na tabela order
   • DrawDB: many-to-one (muitos-para-um)

2. Um-para-Um (1:1): Para divisão de tabelas

   • Exemplo: user (1) → user_profile (1)
   • Implementação: Adicionar user_id UNIQUE na tabela user_profile
   • DrawDB: one-to-one (um-para-um)

3. Muitos-para-Muitos (N:N): Requer tabela de junção

   • Exemplo: article (N) ↔ tag (N)
   • Implementação: Criar tabela de junção article_tag com article_id + tag_id
   • DrawDB: Dois relacionamentos many-to-one (muitos-para-um)

Etapa 4: Gerar Saídas

Crie todos os arquivos de saída necessários:

4.1 Documento de Design Abrangente (Markdown)

Crie um único arquivo Markdown bem estruturado contendo:

Estrutura:

# [Nome do Projeto] Documento de Design de Banco de Dados

## 1. Visão Geral do Banco de Dados
- Tipo de banco de dados
- Conjunto de caracteres
- Número de tabelas principais
- Módulos funcionais principais

## 2. Estrutura das Tabelas

### 2.1 [Nome da Tabela]
**Nome da tabela**: nome_da_tabela
**Descrição**: Descrição da tabela

**Lista de Campos**:
| Nome do Campo | Tipo | Permite Nulo | Valor Padrão | Descrição |
|---------------|------|-------------|--------------|-----------|
| id | BIGINT | NO | | Chave primária |
| ... | ... | ... | ... | ... |

**Lista de Índices**:
| Nome do Índice | Tipo | Campo |
|----------------|------|-------|
| uk_email | UNIQUE | email |
| idx_username | INDEX | username |

### 2.2 [Próxima Tabela]
...

## 3. Descrição dos Relacionamentos entre Tabelas
- tabela1 → tabela2 (1:N): Descrição
- tabela3 ↔ tabela4 (N:N): Descrição via tabela de junção

## 4. Explicação da Estratégia de Índices
Explique a lógica por trás das decisões de design de índices

4.2 Script SQL

Crie um script SQL executável com:

-- Database: nome_do_projeto
-- Gerado: AAAA-MM-DD

-- Remover tabelas se existirem (em ordem de dependência inversa)
DROP TABLE IF EXISTS `tabela3`;
DROP TABLE IF EXISTS `tabela2`;
DROP TABLE IF EXISTS `tabela1`;

-- Criar tabelas (em ordem de dependência)
CREATE TABLE `tabela1` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT 'Comentário',
  ...
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_campo` (`campo`),
  KEY `idx_campo` (`campo`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Comentário da tabela';

CREATE TABLE `tabela2` (
  ...
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Comentário da tabela';

4.3 Formato JSON DrawDB

Gere um arquivo JSON compatível com DrawDB seguindo references/drawdb-formats.md:

Requisitos Críticos de Formato:

• IDs de Tabelas: Use strings aleatórias de 21 caracteres (ex.: "_KV5MtPf2m4sI7Inu8pat")
• IDs de Campos: Use strings aleatórias de 21 caracteres (ex.: "B8rPRTDtOv9oD2Gp4bhWL")
• IDs de Índices: Use incrementos numéricos começando de 0 (em TODAS as tabelas)
• IDs de Relacionamentos: Use strings aleatórias de 21 caracteres
• Tipo de campo: Inclua a definição completa do tipo (ex.: "VARCHAR(100)", não tipo e tamanho separados)
• Sem campo de tamanho: As informações de tipo estão embutidas na string de tipo
• Campos de índice: Use nomes de campo como strings, NÃO IDs de campo (ex.: ["email"] não [1])
• Coordenadas: Use números de ponto flutuante para posições x/y

Geração de ID:

import random
import string

def generate_id():
    chars = string.ascii_letters + string.digits + '_-'
    return ''.join(random.choice(chars) for _ in range(21))

Estratégia de Layout:

• Use layout de grade: x = (index % 3) * 450 + 50, y = floor(index / 3) * 400 + 50
• Alterne por cores predefinidas: ["#6360f7", "#bc49c4", "#ffe159", "#89e667", "#ff9159", "#59d9ff", "#ff5959", "#a0a0a0"]

Geração de Relacionamentos:

• Gere relacionamentos para todos os campos xxx_id de chave estrangeira
• Use os IDs reais de string aleatória para tabelas e campos
• Defina a cardinalidade com base na restrição UNIQUE:
  • Tem UNIQUE → "one_to_one"
  • Sem UNIQUE → "many_to_one"

Estrutura:

{
  "tables": [
    {
      "id": "string_aleatoria",
      "name": "nome_da_tabela",
      "comment": "Comentário da tabela",
      "color": "#6360f7",
      "fields": [
        {
          "id": "string_aleatoria",
          "name": "id",
          "type": "BIGINT",
          "default": "",
          "check": "",
          "primary": true,
          "unique": true,
          "notNull": true,
          "increment": true,
          "comment": "ID da chave primária"
        }
      ],
      "indices": [
        {
          "id": 0,
          "fields": ["nome_do_campo"],
          "name": "idx_nome_do_campo",
          "unique": false
        }
      ],
      "x": 50.0,
      "y": 50.0
    }
  ],
  "relationships": [
    {
      "name": "",
      "startTableId": "string_aleatoria",
      "endTableId": "string_aleatoria",
      "endFieldId": "string_aleatoria",
      "startFieldId": "string_aleatoria",
      "id": "string_aleatoria",
      "updateConstraint": "No action",
      "deleteConstraint": "No action",
      "cardinality": "many_to_one"
    }
  ],
  "notes": [],
  "subjectAreas": [],
  "database": "generic",
  "types": [],
  "title": "Banco de Dados do Projeto"
}

4.4 Formato DBML DrawDB

Gere um arquivo DBML seguindo references/drawdb-formats.md:

Pontos-chave:

• Use tipos de dados em minúsculas: bigint, varchar(50), datetime
• Adicione atributos entre colchetes: [pk, increment, not null, unique, note: 'Comentário']
• Defina índices dentro da definição da tabela no bloco indexes { }
• Defina relacionamentos fora das tabelas usando blocos Ref
• Use símbolos de relacionamento adequados: > (muitos-para-um), - (um-para-um)

Estrutura:

Table nome_da_tabela [headercolor: #6360f7] {
  id bigint [pk, increment, not null, unique, note: 'Comentário']
  campo varchar(100) [not null, note: 'Comentário']
  
  indexes {
    campo [unique, name: 'uk_campo']
  }
  
  Note: 'Comentário da tabela'
}

Ref nome_fk {
  tabela1.campo > tabela2.id [delete: no action, update: no action]
}

Etapa 5: Finalizar e Entregar

5.1 Convenção de Diretório de Saída

Abordagem Recomendada (Seguindo Padrões Oficiais do Claude Code):

Salve todos os arquivos de design de banco de dados em outputs/<nome-do-projeto>/database/:

outputs/
└── <nome-do-projeto>/              # Nome do projeto (ex.: sistema-e-commerce)
    └── database/
        ├── schema-design.md     # Documento de design abrangente
        ├── schema.sql           # Script SQL executável
        ├── drawdb-schema.json   # Formato JSON DrawDB
        └── drawdb-schema.dbml   # Formato DBML DrawDB

Exemplo:

outputs/
├── sistema-e-commerce/
│   └── database/
│       ├── schema-design.md
│       ├── schema.sql
│       ├── drawdb-schema.json
│       └── drawdb-schema.dbml
└── app-gerenciamento-tarefas/
    └── database/
        ├── schema-design.md
        └── schema.sql

Abordagem Alternativa (Estrutura de Projeto Tradicional):

Se seu projeto já possui uma estrutura de diretórios existente, você também pode usar:

raiz-do-projeto/
└── database/
    ├── schema-design.md
    ├── schema.sql
    ├── drawdb-schema.json
    └── drawdb-schema.dbml

5.2 Lista de Arquivos de Saída

Saídas Obrigatórias (4 arquivos):

• schema-design.md - Documento de design de banco de dados abrangente
• schema.sql - Script SQL executável
• drawdb-schema.json - Formato JSON DrawDB
• drawdb-schema.dbml - Formato DBML DrawDB

Saídas Opcionais:

• er-diagram.png - Visualização do diagrama ER (se ferramentas disponíveis)
• index-strategy.md - Documentação da estratégia de índices

5.3 Convenção de Nomenclatura de Arquivos

• Use kebab-case: autenticacao-usuario-schema.sql
• Inclua versão/data quando necessário: schema-v1.0.sql ou schema-2024-12-10.sql
• Use nomes descritivos: e-commerce-database-schema.sql

5.4 Resumo da Entrega

Após gerar todos os arquivos, forneça um resumo com:

• Breve visão geral das decisões de design
• Número de tabelas criadas
• Relacionamentos principais e sua lógica
• Como importar no DrawDB (JSON ou DBML)
• Confirmação do local de salvamento dos arquivos
• Sugestões de próximos passos (ex.: revisar índices, implementar em ambiente de desenvolvimento)

Tratamento Especial

Quando o Usuário Diz "Sem Campos de Sistema"

Crie apenas a estrutura mínima:

CREATE TABLE `nome_da_tabela` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT 'Chave primária',
  /* apenas campos de negócio */
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Comentário da tabela';

Quando o Usuário Especifica um Banco de Dados Não-MySQL

Adapte a sintaxe SQL de acordo:

PostgreSQL:

• Use SERIAL ou BIGSERIAL em vez de AUTO_INCREMENT
• Use TIMESTAMP em vez de DATETIME
• Sintaxe diferente para valores padrão e restrições

SQL Server:

• Use IDENTITY(1,1) em vez de AUTO_INCREMENT
• Use DATETIME2 em vez de DATETIME
• Use NVARCHAR para suporte a Unicode

Oracle:

• Use SEQUENCE para auto-incremento
• Use VARCHAR2 em vez de VARCHAR
• Use DATE ou TIMESTAMP para campos de data/hora

Quando os Requisitos São Vagos

Aplique inferência inteligente:

1. Identifique o domínio de negócio (e-commerce, blog, CRM, etc.)
2. Consulte exemplos similares em references/design-examples.md
3. Inclua campos comuns apropriados ao domínio
4. Projete índices razoáveis com base em padrões típicos de consulta
5. Explique as suposições feitas no documento de design

Verificação de Qualidade

Antes de finalizar, verifique:

• Todas as tabelas têm COMMENT
• Todos os campos têm COMMENT
• Os tamanhos dos campos são realistas (não VARCHAR(255) genérico)
• Quantidade de índices por tabela ≤ 5
• Nenhuma restrição FOREIGN KEY física
• Campos de sistema adicionados (a menos que o usuário especifique o contrário)
• Todos os nomes usam snake_case
• Relacionamentos lógicos documentados claramente
• A sintaxe SQL corresponde ao tipo de banco de dados de destino
• Os formatos JSON/DBML seguem as especificações do DrawDB
• Todos os relacionamentos de chave estrangeira têm entradas Ref correspondentes

Exemplos de Invocação

Usuário diz: "Projete um banco de dados para um sistema de e-commerce, incluindo funcionalidades de usuários, produtos e pedidos" → Leia design-principles.md e design-examples.md → Projete: tabelas user_info, product_info, order_info, order_detail → Gere todos os 4 arquivos de saída

Usuário diz: "Projete um banco de dados para blog" → Infira: tabelas user, article, comment, tag, article_tag → Siga os princípios padrão de design → Gere todas as saídas

Usuário diz: "Crie uma tabela de usuários para PostgreSQL" → Design de tabela única → Adapte a sintaxe SQL para PostgreSQL → Inclua em todos os formatos de saída

Referências

• references/design-principles.md - Regras e padrões centrais de design
• references/drawdb-formats.md - Especificações de formato JSON e DBML
• references/design-examples.md - Exemplos de design do mundo real