MeowSpool/PRD.md

# Product Requirements Document (PRD): MeowSpool

# Paper Canva
https://app.paper.design/file/01KKM0HA6NBV44VCQDFQHC2MRY

## 1. Visão Geral

MeowSpool é uma solução para entusiastas e profissionais de impressão 3D gerenciarem seu estoque de filamentos. O diferencial está na precisão do cálculo de peso líquido (descontando o peso do carretel via presets), na identidade visual inspirada em gatos siameses, e na integração com etiquetas físicas exportáveis (SVG/QR Code/NFC).

**Foco do desenvolvimento atual:** App Mobile (React Native) + Backend em Rust. A interface Web é planejada para uma fase posterior, após a estabilização do mobile e da API.

---

## 2. Objetivos

* **Precisão:** Eliminar o "chute" de quanto filamento resta no rolo.
* **Agilidade:** Facilitar o cadastro e a consulta via dispositivos móveis, mesmo offline.
* **Organização:** Centralizar parâmetros técnicos (temperatura/fluxo) para consulta rápida.

---

## 3. Público-Alvo

* Hobbistas de impressão 3D.
* Donos de "Print Farms" (fazendas de impressão).
* Projetistas que trabalham com diversos materiais (PLA, ABS, PETG, etc).

---

## 4. Identidade Visual

### 4.1 Nome e Conceito
**MeowSpool** — fusão de "Meow" (gato) e "Spool" (carretel). A identidade visual é inspirada no gato siamês: tons quentes e escuros com detalhes em azul-aço que remetem aos olhos característicos da raça.

### 4.2 Paleta de Cores

| Token         | Hex       | Função na Interface                          |
|---------------|-----------|----------------------------------------------|
| `bg-base`     | `#1E1B18` | Fundo geral                                  |
| `bg-surface`  | `#2A2622` | Cards, contêineres, widgets                  |
| `bg-hover`    | `#332F2B` | Estados de hover em cards e itens de lista   |
| `text-primary`| `#F5EEDC` | Títulos, peso líquido (texto importante)     |
| `text-secondary`| `#C9C1B0`| Descrições, labels (material, marca)        |
| `accent`      | `#38BCC2` | Botões de ação, elementos ativos             |
| `accent-muted`| `#38BCC226`| Backgrounds de badges e status (10% opacidade)|

---

## 5. Requisitos Funcionais (MVP)

### 5.1 Autenticação

* **Métodos suportados:** Email/senha e OAuth via Google.
* **Plataformas:** Mobile consome a API de auth do backend Rust. Web utilizará o mesmo sistema em fase futura.
* **Sessão:** Token JWT com refresh token. O app mobile persiste a sessão localmente para acesso offline.

### 5.2 Gestão de Inventário

* **Cadastro de Filamento:** Campos obrigatórios e opcionais:
  * Material (tipo): PLA, ABS, PETG, TPU, ASA, PA, PC, etc.
  * Marca (texto livre)
  * Modelo (texto livre)
  * Cor (seletor hex — armazena valor hexadecimal, ex: `#FF5733`)
  * Temperatura Hotend (°C)
  * Temperatura Mesa (°C)
  * Fator de Fluxo/Extrusão (%)

* **Calculadora de Peso Líquido:**
  * Seleção de **Preset de Carretel** (ver 5.3).
  * Input de **Peso Total** (leitura da balança, em gramas).
  * Cálculo automático: `Peso_Líquido = Peso_Total - Peso_Carretel`.

### 5.3 Presets de Carretéis

* **Presets do Sistema (built-in):** Um conjunto de presets pré-cadastrados com as principais marcas do mercado. Exemplos:

  | Nome do Preset         | Peso do Carretel |
  |------------------------|-----------------|
  | Bambu Lab (Plástico)   | 250g            |
  | Elegoo (Papelão)       | 200g            |
  | Creality (Plástico)    | 230g            |
  | Prusament (Plástico)   | 201g            |
  | Sunlu (Papelão)        | 200g            |
  | Polymaker (Plástico)   | 220g            |
  | Genérico Papelão 1kg   | 200g            |
  | Genérico Plástico 1kg  | 250g            |

* **Presets Customizados:** O usuário pode criar, editar e excluir seus próprios presets (nome + peso em gramas). Presets customizados são vinculados à conta do usuário e sincronizados.
* **Presets do sistema são somente leitura** — não podem ser editados ou excluídos pelo usuário.

### 5.4 Identificação e Etiquetas

* **Geração de QR Code:** Cada filamento cadastrado gera um QR Code único apontando para sua página de detalhes no app/web.
* **Exportação de Etiqueta em SVG:** O sistema gera um arquivo SVG com os dados do filamento (nome, material, cor, peso líquido, QR Code) para que o usuário importe e imprima na plataforma de sua preferência (Inkscape, Canva, impressoras de etiqueta com suporte a SVG, etc).
  * Layout padrão: 50mm x 30mm (ajustável via parâmetro).
  * Conteúdo: cor visual do filamento, nome, material, marca, peso líquido, QR Code.

### 5.5 Interface (UI/UX)

* **Design:** Dark mode exclusivo, paleta siamês (ver 4.2).
* **Plataforma atual:** Mobile (React Native).
* **Filtros e Busca:** Filtragem por material, marca, cor e nível de estoque.
* **Dashboard:** Visão geral do inventário com totais por material e alertas visuais de estoque baixo.

---

## 6. Requisitos Técnicos (Stack)

### 6.1 Fase 1 — Mobile + Backend (foco atual)

| Camada            | Tecnologia           | Justificativa                                                                |
|-------------------|----------------------|------------------------------------------------------------------------------|
| **Mobile**        | React Native         | Performance nativa, suporte offline e acesso a APIs do dispositivo (câmera, NFC). |
| **Back-end**      | Rust (Axum ou Actix) | Alta performance, segurança de memória e baixo consumo de recursos.         |
| **Banco de Dados**| PostgreSQL           | Robustez para relações entre usuários, marcas, materiais e presets.         |
| **Auth**          | JWT + OAuth (Google) | Padrão seguro, compatível com mobile e preparado para web futura.           |
| **Banco Local**   | SQLite (SQLCipher)   | Armazenamento offline seguro no dispositivo móvel.                          |

### 6.2 Fase 2 — Web (planejado, pós-estabilização)

| Camada            | Tecnologia     | Justificativa                                              |
|-------------------|----------------|------------------------------------------------------------|
| **Front-end Web** | Next.js        | SEO, performance, rotas e suporte a cache via ISR/SSR.    |
| **Cache (Web)**   | Redis / HTTP Cache | Redução de latência nas listagens e dados de inventário.|

### 6.3 Estratégia de Sincronização (Offline-First Mobile)

1. O app mobile utiliza um banco de dados local (SQLite via SQLCipher para segurança).
2. Todas as operações são escritas localmente primeiro (write-ahead).
3. Quando há conexão, o app sincroniza via API REST com o backend Rust (estratégia: last-write-wins com timestamp, com resolução de conflitos simples).
4. A Web (fase 2) consumirá a mesma API REST, sem necessidade de alterações no backend.

---

## 7. Estrutura de Dados (Entidades Principais)

### `users`
| Campo        | Tipo      | Descrição                        |
|--------------|-----------|----------------------------------|
| id           | UUID      | Identificador único              |
| email        | string    | Email do usuário                 |
| password_hash| string    | Hash bcrypt (nulo se OAuth)      |
| google_id    | string?   | ID OAuth Google (opcional)       |
| created_at   | timestamp |                                  |

### `spool_presets`
| Campo        | Tipo      | Descrição                                      |
|--------------|-----------|------------------------------------------------|
| id           | UUID      | Identificador único                            |
| name         | string    | Nome do preset (ex: "Bambu Lab Plástico")      |
| spool_weight_g| integer  | Peso do carretel vazio em gramas               |
| is_system    | boolean   | `true` = preset built-in, `false` = customizado|
| user_id      | UUID?     | Nulo para presets do sistema                   |
| created_at   | timestamp |                                                |

### `filaments`
| Campo            | Tipo      | Descrição                              |
|------------------|-----------|----------------------------------------|
| id               | UUID      | Identificador único                    |
| user_id          | UUID      | Dono do filamento                      |
| material         | string    | PLA, ABS, PETG, etc.                   |
| brand            | string    | Marca                                  |
| model            | string?   | Modelo/linha                           |
| color_hex        | string    | Cor em hex (ex: `#FF5733`)             |
| spool_preset_id  | UUID      | Preset de carretel usado               |
| total_weight_g   | integer   | Peso total medido na balança (gramas)  |
| net_weight_g     | integer   | Calculado: total - preset              |
| temp_hotend_c    | integer?  | Temperatura do hotend (°C)             |
| temp_bed_c       | integer?  | Temperatura da mesa (°C)               |
| flow_factor_pct  | float?    | Fator de fluxo (%)                     |
| notes            | text?     | Observações livres                     |
| updated_at       | timestamp | Usado para sync offline                |
| created_at       | timestamp |                                        |

---

## 8. Fluxo do Usuário (User Flow)

### Cadastro de Filamento (Mobile)
1. Usuário abre o App Mobile (autenticado).
2. Clica em "Novo Filamento".
3. Insere Marca, Material, Modelo e seleciona a Cor via seletor hex.
4. Seleciona o Preset do Carretel (ex: "Bambu Lab Plástico — 250g") ou cria um customizado.
5. Coloca o carretel na balança e digita o peso total (ex: "850g").
6. O sistema calcula e exibe: **600g de filamento disponível**.
7. Salva localmente (offline-first) e sincroniza com o backend quando online.
8. O sistema gera o QR Code e disponibiliza o SVG da etiqueta para exportação.

### Consulta via Web *(Fase 2 — planejado)*
1. Usuário acessa a web autenticado.
2. Dashboard exibe inventário completo com totais e alertas.
3. Dados são servidos via API com cache, garantindo baixa latência.

---

## 9. Roadmap de Funcionalidades Futuras

* **Front-end Web (Next.js):** Dashboard e inventário acessível via browser, consumindo a mesma API do backend.
* **Escrita de Tags NFC:** Gravação de dados diretamente em tags NFC coladas nos carretéis (via app mobile).
* **Histórico de Uso:** Log de gramas consumidas por projeto/impressão.
* **Alerta de Estoque Baixo:** Notificações push quando um filamento estiver abaixo de X gramas.
* **Custo por Grama:** Registro do custo de cada rolo para cálculo de custo por impressão.
* **Importação em Lote:** Upload CSV/JSON para cadastro massivo (útil para print farms).
* **Compartilhamento de Presets:** Pool público de presets de carretéis contribuídos pela comunidade.