# Citrus — Sistema de Gestão de Diárias
## Spec 1: Fundação + Cadastros — Documento de Design

| Campo | Valor |
| :---- | :---- |
| Projeto | Citrus Engenharia — Sistema de Gestão de Diárias |
| Spec | 1 de N (Fundação + Cadastros) |
| Data | 2026-06-18 |
| Stack | Docker + PHP 8.2 + Yii2 (app-basic) + MySQL 8.0 + Bootstrap5 |
| Plataforma | Web responsivo, mobile-first (shell de app) |
| Requisitos-fonte | `Citrus_Requisitos_v1.0.docx.md` |

---

## 0. Contexto e decomposição

O documento de requisitos v1.0 descreve um sistema completo (auth, cadastros, efetivo/ponto,
fechamento de card quinzenal, dashboard, relatórios dinâmicos, auditoria). É grande demais para
um único plano de implementação, então foi fatiado em specs sequenciais — cada um construído e
testado isoladamente:

1. **Spec 1 (este documento): Fundação + Cadastros** — scaffold, Docker, app-shell mobile, tema,
   favicon, autenticação, transversais (soft-delete + auditoria + export), e o módulo de Cadastros
   (Funções, Profissionais, Obras).
2. Spec 2: Efetivo (ponto diário com GPS + foto).
3. Spec 3: Fechamento de Card (holerite quinzenal + PDF).
4. Spec 4: Dashboard (KPIs, gráficos, painel de alertas).
5. Spec 5: Relatórios dinâmicos (SQL cadastrado em banco).

O `citrus/` é uma subpasta do repositório `projects`, ao lado de apps Yii2 irmãos
(`london`, `ismbr`). Este spec espelha as convenções já estabelecidas nesses projetos para manter
um padrão único de operação e desenvolvimento.

---

## 1. Stack & infraestrutura

- **Template**: Yii2 `yii2-app-basic`, PHP 8.2, `yiisoft/yii2-bootstrap5`.
- **Docker** (espelha london): serviços `nginx` (`nginx:1.27-alpine`), `php` (build próprio em
  `.docker/php`), `db` (`mysql:8.0`).
- **Portas** (london usa 8081/3307 — evitar conflito): nginx → **`8082`**, mysql host → **`3308`**.
- **Configuração**: `.env` + `.env.example` com `MYSQL_ROOT_PASSWORD`, `MYSQL_DATABASE=citrus`,
  `MYSQL_USER`, `MYSQL_PASSWORD`, `DB_HOST`, `DB_PORT`, `YII_ENV`, `YII_DEBUG`.
- **Qualidade**: `phpstan`, `phpcs`, `codeception` configurados como nos projetos irmãos.
- **Migrations**: toda a estrutura de dados via migrations Yii2 (sem schema manual).

---

## 2. App-shell & tema

Direção visual validada com o cliente (mockups no companion):

- **Tema claro**, alto contraste (uso em campo, sob sol forte).
- **Paleta da marca** (extraída da `logo.png`):
  - Lime `#C0F024` — CTA/acento (sempre com texto escuro por cima; nunca como texto sobre branco).
  - Green `#9CCC6C` — secundária / estado de sucesso.
  - Ink `#0C0C0C` — texto e superfícies escuras.
  - Grays `#303030`–`#787878` — texto auxiliar.
- **Camada de CSS própria** (`web/css/app.css`) com tokens de cor/spacing/raio, **sobre** o
  Bootstrap5 (forms, grid, utilidades permanecem do Bootstrap, mantendo consistência com as irmãs).
- **Shell mobile** (layout principal):
  - Header com a logo Citrus.
  - **Bottom tab bar** fixa.
  - **FAB lime "＋"** central elevado → ação primária "Registrar efetivo".
  - Em telas largas (desktop), o conteúdo fica centralizado/travado em largura de app.
- **Navegação por perfil**:
  - Admin/Gerente: `Início · Obras · ＋ · Efetivo · Mais`.
  - Líder: `Início · ＋ · Mais`.
  - "Mais" (folha que sobe): `Cards · Relatórios · Cadastros (Funções/Profissionais/Obras) · Perfil/Sair`.
  - Itens são filtrados pela tabela de permissões do perfil.
  - **Neste spec**, os destinos `Efetivo`, `Cards`, `Relatórios` existem como **stubs**
    (placeholder "em breve"); só `Início`, `Obras`, `Cadastros`, auth e o shell ficam funcionais.
- **Favicon / PWA-like**: conjunto gerado a partir de `isologo.png` (16, 32, 180 apple-touch,
  192, 512) + `site.webmanifest` para dar cara de app ao adicionar à tela inicial.
- **Logo**: incluída no header do sistema (e, em spec futuro, no PDF do card).

---

## 3. Autenticação & identidade

- **Identidade do sistema = `Profissional`** — login e senha são colunas do profissional
  (não há tabela `user` separada). O perfil `Profissional` puro não acessa o sistema.
- **Múltiplos perfis por usuário**: coluna `perfis` como `SET('profissional','lider','gerente','administrativo')`
  (consultável via `FIND_IN_SET`, ex.: listar profissionais com perfil Líder).
- **Login**: campo `login` + senha (hash via `Yii::$app->security->generatePasswordHash`),
  com **CAPTCHA** nativo do Yii (`yii\captcha\CaptchaAction` + validador `captcha`).
- **Bloqueio de conta**: colunas `failed_attempts` e `locked_until` em `profissionais`.
  N de tentativas configurável em `params.php` (padrão **5**); ao exceder, bloqueia por janela
  configurável.
- **Sessão**: timeout configurável em `params.php` (padrão **60 min**).
- **Autorização**: tabela `permissoes` (perfil → tela → ações). Um componente/`AccessControl`
  próprio resolve o acesso lendo essa tabela. **Sem UI de edição na v1.0** — manutenção direta no
  banco (seed inicial via migration).

---

## 4. Transversais (construídos neste spec, usados por todos os módulos)

### 4.1 Soft-delete
- Coluna `deleted_at` em todas as entidades.
- *Behavior* base reutilizável + *default scope* que filtra registros excluídos em todas as
  queries padrão. Nenhuma exclusão física.

### 4.2 Auditoria
- *Behavior* global anexado aos `ActiveRecord` que registra `INSERT`, `UPDATE`, `SOFT_DELETE` e
  `STATUS_CHANGE` na tabela `auditoria`.
- Campos: `id`, `tabela`, `registro_id`, `acao`, `dados_anteriores` (JSON, null em INSERT),
  `dados_novos` (JSON, null em SOFT_DELETE), `usuario_id`, `ip`, `created_at`.

### 4.3 Export Excel
- Helper/ação reutilizável (PhpSpreadsheet) — requisito "toda listagem exporta para Excel".
- Neste spec, plugado nas listagens dos cadastros; reutilizável pelos módulos futuros.

---

## 5. Módulo de Cadastros (CRUD — acesso Administrativo)

### 5.1 Funções
| Campo | Tipo | Obrigatório | Observações |
| :-- | :-- | :-- | :-- |
| Nome | Texto | Sim | Ex.: Pedreiro, Pintor, Engenheiro |
| Tipo de remuneração | Select (diária/quinzena) | Sim | Define qual valor é exigido |
| Valor base diária | Monetário | Condicional | Obrigatório se tipo = diária |
| Valor base quinzena | Monetário | Condicional | Obrigatório se tipo = quinzena |
| Status | Toggle | Sim | Ativo / Inativo |

Os valores servem de padrão para novos profissionais, mas são sobrescrevíveis no cadastro do profissional.

### 5.2 Profissionais
| Campo | Tipo | Obrigatório | Observações |
| :-- | :-- | :-- | :-- |
| Nome completo | Texto | Sim | |
| CPF | Texto (máscara) | Sim | Único no sistema |
| CNPJ | Texto (máscara) | Não | MEI |
| Razão Social | Texto | Não | |
| Data de nascimento | Data | Sim | |
| Endereço | Texto | Sim | |
| WhatsApp | Texto (máscara) | Sim | |
| E-mail | Texto | Não | |
| Função | Select | Sim | Apenas funções ativas; uma por profissional |
| Valor diária | Monetário | Sim | Pré-carregado da função, editável |
| Perfis | Checkbox múltiplo | Sim | Profissional / Líder / Gerente / Administrativo |
| Valor bônus mensal | Monetário | Condicional | Visível só se perfil Líder |
| Login | Texto | Condicional | Obrigatório se Líder/Gerente/Administrativo |
| Senha | Senha | Condicional | Obrigatório se Líder/Gerente/Administrativo |
| Status | Select | Sim | Ativo / Inativo / Afastado |

Validações condicionais implementadas no model (regras dependentes do tipo da função e dos perfis selecionados).

### 5.3 Obras
| Campo | Tipo | Obrigatório | Observações |
| :-- | :-- | :-- | :-- |
| Nome da obra | Texto | Sim | |
| Cliente | Texto | Sim | |
| Turno | Texto livre | Sim | |
| CEP | Texto (máscara) | Sim | **Busca automática (ViaCEP)** preenche bairro/endereço/UF/cidade |
| Bairro | Texto | Sim | |
| Endereço | Texto | Sim | |
| Número | Texto | Sim | |
| UF | Select | Sim | |
| Cidade | Texto | Sim | |
| Líder Obra 1 | Select | Não | `lider1_id` → profissionais com perfil Líder |
| Líder Obra 2 | Select | Não | `lider2_id` → profissionais com perfil Líder |
| Status | Select | Sim | Ativo / Inativo |

### 5.4 Listagens
- Filtros conforme cada entidade, cards mobile (não tabela densa), e **export Excel** da listagem filtrada.

---

## 6. Modelo de dados (Spec 1)

Tabelas criadas neste spec (todas com `deleted_at`, `created_at`, `updated_at`):

| Tabela | Finalidade |
| :-- | :-- |
| `profissionais` | Trabalhadores MEI + identidade do sistema (perfis, função, valores, login/senha, bloqueio) |
| `funcoes` | Funções com tipo de remuneração e valores padrão |
| `obras` | Obras com endereço, turno, `lider1_id`/`lider2_id`, status |
| `permissoes` | Mapeamento perfil → tela → ações (manutenção via banco) |
| `auditoria` | Log de todas as operações |

Relações: `profissionais.funcao_id → funcoes.id`; `obras.lider1_id/lider2_id → profissionais.id`.
Tabelas dos módulos futuros (`efetivo`, `cards`, `card_itens`, `card_status_historico`,
`relatorios`) ficam fora deste spec.

---

## 7. Testes

Codeception (unit + functional), no padrão dos projetos irmãos:
- Unit: validações condicionais dos models (Função tipo×valor; Profissional perfis×login/senha×bônus),
  soft-delete e auditoria disparando corretamente.
- Functional: fluxo de login (sucesso, CAPTCHA, bloqueio após N tentativas), e CRUDs de
  Funções/Profissionais/Obras incluindo busca de CEP e export Excel.

---

## 8. Fora do escopo deste spec

Efetivo/ponto diário, fechamento de card, dashboard, relatórios dinâmicos, geração de PDF e
integração com WhatsApp — cada um endereçado em seu próprio spec subsequente.