Especificação do Módulo de Tarefas

Sistema de origem: Organiza
Versão: 2.0
Finalidade deste documento: servir de referência completa (funcional + dados + APIs + regras) para reimplementar o módulo em outro projeto.

Sumário

Visão geral
Escopo
Glossário
Arquitetura e multi-tenant
Modelo de dados
Relacionamentos
Enums e catálogos
Permissões e visibilidade
Regras de negócio
Telas e capacidades UX
Contrato de APIs
Armazenamento de arquivos
Auditoria e logs
Integrações
Fluxos principais
Sugestões para reimplementação
Critérios de aceitação

1. Visão geral

O módulo de Tarefas permite que cada empresa (tenant) planeje, execute e acompanhe trabalho operacional.

Ciclo operacional

Etapa	Capacidade
Criar	Tarefa unitária ou em lote
Organizar	Status, prioridade, prazo, projeto (nome), responsável
Executar	Checklist (passos), documentos, fluxo operacional
Colaborar	Comentários internos + histórico
Acompanhar	Listagem, Kanban, dashboard, link público de projeto
Resumir	Resumo executivo por IA (opcional)

Princípios

Princípio	Detalhe
Multi-tenant	Toda tarefa tem `tenant_id`; isolamento obrigatório
Módulo opcional	Em white label, liga/desliga via `tenant_modules.module = 'tasks'`
Sem FK com CRM	Não há vínculo estrutural com leads/clientes
Projeto por nome	`tasks.project` é `VARCHAR` (match com `projects.name`), não FK

2. Escopo

2.1 Dentro do escopo

CRUD de tarefas
Listagem filtrada + paginação
Kanban por status
Checklist (passos)
Documentos anexos
Fluxo operacional (etapas ordenadas)
Comentários e histórico da tarefa
Atribuição de responsável
Resumo por IA
KPIs de operação no dashboard
Vínculo lógico com projetos + página pública de acompanhamento

2.2 Fora do escopo (no Organiza atual)

Drag-and-drop no Kanban
FK real tarefa ↔ projeto
Vínculo tarefa ↔ lead/cliente
Enforcement da flag tarefas.block
Filtro distinto para tarefas.read_filtered (hoje = read_all)

3. Glossário

Termo	Significado
Tarefa	Unidade de trabalho (`tasks`)
Status	Estado do ciclo: pending / started / completed / cancelled
Prioridade	low / medium / high
Passo	Item de checklist (`task_steps`)
Documento	Anexo da tarefa (`task_documents`)
Fluxo operacional	Sequência numerada de etapas (`task_activity_flow_steps`)
Timeline da tarefa	UI derivada do `status` (Pendente → Iniciada → Concluída)
Projeto	Cadastro separado (`projects`); ligado à tarefa por nome
Tenant	Empresa / white label
TaskPolicy	Camada de visibilidade (próprias vs todas)

4. Arquitetura e multi-tenant

4.1 Gate do módulo

Conceito	Valor
Tabela	`tenant_modules`
Chave do módulo	`module = 'tasks'`
Plataforma (tenant id = 1)	Sempre habilitado
White label	Checkbox no CRUD de WL
Ao ligar	Habilita módulo + concede permissões padrão aos admins
Ao desligar	Menu/API/grupo somem; dados preservados

CREATE TABLE tenant_modules (
    tenant_id INT UNSIGNED NOT NULL,
    module    VARCHAR(60) NOT NULL,   -- 'tasks' | 'leads' | ...
    enabled   TINYINT(1) NOT NULL DEFAULT 0,
    updated_at DATETIME NULL,
    PRIMARY KEY (tenant_id, module),
    CONSTRAINT fk_tenant_modules_tenant
        FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
);

4.2 Camadas de enforcement

Camada	Comportamento se módulo OFF
Páginas (`tarefas.php`, `kanban.php`)	HTTP 403
APIs (`api/tarefas/**`, kanban, KPIs)	JSON 403
Permissões `tarefas.*`	Sempre `false`
Sidebar	Links ocultos
Dashboard	Aba Operação oculta

4.3 Isolamento de dados

Toda query/mutação filtra por tenant_id da sessão.
Filhos (steps, docs, flow, comments, history) não têm tenant_id próprio — herdam via task_id + CASCADE.
Leitura adicional via TaskPolicy (próprias / todas).

5. Modelo de dados

5.1 Mapa de tabelas do módulo

Tabela	Papel	Dependência
`tasks`	Entidade principal	`tenants`, `users`
`task_steps`	Checklist	`tasks`, `users`
`task_documents`	Anexos	`tasks`, `users`
`task_activity_flow_steps`	Fluxo operacional	`tasks`, `users`
`task_comments`	Comentários	`tasks`, `users`
`task_history`	Auditoria da tarefa	`tasks`
`projects`	Cadastro de projetos (satélite)	`tenants`, `clients`
`tenant_modules`	Liga/desliga módulo	`tenants`
`permissions`	Catálogo de flags	—
`user_permissions`	Flags por usuário	`users`, `permissions`
`logs`	Log global do sistema	`tenants`

5.2 Diagrama ER

erDiagram
    tenants ||--o{ users : possui
    tenants ||--o{ tasks : possui
    tenants ||--o{ projects : possui
    tenants ||--o{ tenant_modules : configura

    users ||--o{ tasks : created_by
    users ||--o{ tasks : assigned_to
    users ||--o{ task_steps : created_by
    users ||--o{ task_documents : uploaded_by
    users ||--o{ task_activity_flow_steps : created_by
    users ||--o{ task_comments : user_id
    users ||--o{ user_permissions : possui
    permissions ||--o{ user_permissions : define

    tasks ||--o{ task_steps : tem
    tasks ||--o{ task_documents : tem
    tasks ||--o{ task_activity_flow_steps : tem
    tasks ||--o{ task_comments : tem
    tasks ||--o{ task_history : registra

    projects }o..o{ tasks : "vinculo logico por nome"
    clients ||--o{ projects : opcional

5.3 Tabela `tasks`

CREATE TABLE tasks (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id INT UNSIGNED NOT NULL,
    title VARCHAR(180) NOT NULL,
    description TEXT NULL,
    project VARCHAR(120) NULL,                          -- nome do projeto (NAO FK)
    status ENUM('pending','started','completed','cancelled') NOT NULL DEFAULT 'pending',
    previous_status ENUM('pending','started','completed','cancelled') NULL,
    priority ENUM('low','medium','high') NOT NULL DEFAULT 'medium',
    assigned_to INT UNSIGNED NULL,
    created_by INT UNSIGNED NOT NULL,
    due_date DATE NULL,
    ai_summary TEXT NULL,
    ai_transcription LONGTEXT NULL,
    ai_summary_generated_at DATETIME NULL,
    completed_at DATETIME NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NULL,

    KEY idx_tasks_tenant (tenant_id),
    KEY idx_tasks_status (status),
    KEY idx_tasks_due_date (due_date),
    KEY idx_tasks_assigned_to (assigned_to),
    KEY idx_tasks_created_by (created_by),

    CONSTRAINT fk_tasks_tenant
        FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE RESTRICT,
    CONSTRAINT fk_tasks_assigned_to
        FOREIGN KEY (assigned_to) REFERENCES users(id) ON DELETE SET NULL,
    CONSTRAINT fk_tasks_created_by
        FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE CASCADE
);

Campo	Tipo	Obrigatório	Regras
`id`	INT UNSIGNED	PK	Auto
`tenant_id`	INT UNSIGNED	Sim	FK tenants, RESTRICT
`title`	VARCHAR(180)	Sim	Mín. 3 caracteres
`description`	TEXT	Não	—
`project`	VARCHAR(120)	Não	Match textual com `projects.name`
`status`	ENUM	Sim	Default `pending`
`previous_status`	ENUM	Não	Usado no toggle Kanban
`priority`	ENUM	Sim	Default `medium`
`assigned_to`	INT UNSIGNED	Não	FK users, SET NULL
`created_by`	INT UNSIGNED	Sim	FK users, CASCADE
`due_date`	DATE	Não	Dias úteis + janela (ver regras)
`ai_summary`	TEXT	Não	Preenchido pela IA
`ai_transcription`	LONGTEXT	Não	Extração dos anexos
`ai_summary_generated_at`	DATETIME	Não	Timestamp da geração
`completed_at`	DATETIME	Não	Só quando `status = completed`
`created_at` / `updated_at`	TIMESTAMP/DATETIME	—	Auditoria temporal

5.4 Tabela `task_steps` (checklist)

CREATE TABLE task_steps (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    task_id INT UNSIGNED NOT NULL,
    title VARCHAR(180) NOT NULL,          -- min. 2
    is_done TINYINT(1) NOT NULL DEFAULT 0,
    created_by INT UNSIGNED NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NULL,
    CONSTRAINT fk_task_steps_task
        FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE,
    CONSTRAINT fk_task_steps_created_by
        FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE CASCADE
);

5.5 Tabela `task_documents`

CREATE TABLE task_documents (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    task_id INT UNSIGNED NOT NULL,
    original_name VARCHAR(180) NOT NULL,
    file_name VARCHAR(220) NOT NULL,
    file_path VARCHAR(255) NOT NULL,
    mime_type VARCHAR(120) NULL,
    file_size INT UNSIGNED NULL,
    uploaded_by INT UNSIGNED NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT fk_task_documents_task
        FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE,
    CONSTRAINT fk_task_documents_uploaded_by
        FOREIGN KEY (uploaded_by) REFERENCES users(id) ON DELETE CASCADE
);

5.6 Tabela `task_activity_flow_steps`

CREATE TABLE task_activity_flow_steps (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    task_id INT UNSIGNED NOT NULL,
    title VARCHAR(180) NOT NULL,           -- min. 2
    sort_order INT UNSIGNED NOT NULL DEFAULT 1,  -- MAX(sort_order)+1
    created_by INT UNSIGNED NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT fk_task_activity_flow_steps_task
        FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE,
    CONSTRAINT fk_task_activity_flow_steps_created_by
        FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE CASCADE
);

5.7 Tabela `task_comments`

CREATE TABLE task_comments (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    task_id INT UNSIGNED NOT NULL,
    user_id INT UNSIGNED NOT NULL,
    user_name VARCHAR(120) NOT NULL,       -- snapshot do nome
    comment TEXT NOT NULL,                 -- min. 2
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_task_comments_task (task_id),
    CONSTRAINT fk_task_comments_task
        FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE,
    CONSTRAINT fk_task_comments_user
        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

5.8 Tabela `task_history`

CREATE TABLE task_history (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    task_id INT UNSIGNED NOT NULL,
    user_id INT UNSIGNED NULL,             -- sem FK (snapshot)
    user_name VARCHAR(120) NOT NULL,
    action VARCHAR(80) NOT NULL,
    description VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_task_history_task (task_id),
    INDEX idx_task_history_created_at (created_at),
    CONSTRAINT fk_task_history_task
        FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE
);

5.9 Tabela `projects` (satélite)

Usada pelo módulo de tarefas via nome, não FK.

CREATE TABLE projects (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id INT UNSIGNED NOT NULL,
    client_id INT UNSIGNED NULL,
    name VARCHAR(120) NOT NULL,
    description TEXT NULL,
    project_type VARCHAR(60) NULL,
    start_date DATE NULL,
    delivery_forecast DATE NULL,
    contract_value DECIMAL(12,2) NULL,
    billing_type ENUM('setup','mensalidade','setup_mensalidade') NULL,
    setup_value DECIMAL(12,2) NULL,
    monthly_value DECIMAL(12,2) NULL,
    billing_due_day TINYINT UNSIGNED NULL,
    status ENUM('pending','in_progress','completed','paused') NOT NULL DEFAULT 'pending',
    public_token VARCHAR(80) NULL UNIQUE,
    public_link_access_count INT UNSIGNED NOT NULL DEFAULT 0,
    public_link_last_accessed_at DATETIME NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NULL,
    UNIQUE KEY uniq_projects_tenant_name (tenant_id, name),
    CONSTRAINT fk_projects_tenant
        FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE RESTRICT,
    CONSTRAINT fk_projects_client
        FOREIGN KEY (client_id) REFERENCES clients(id) ON DELETE SET NULL
);

Integração com tarefas	Regra
Contagem	`COUNT(*) WHERE tasks.project = projects.name AND same tenant`
Exclusão de projeto	Bloqueada se `task_count > 0`
Renomear projeto	Não atualiza `tasks.project` automaticamente
Link público	`projeto-status.php?token={public_token}` lista tarefas pelo nome

5.10 Tabelas de suporte (já existentes no sistema)

Tabela	Uso no módulo
`tenants`	Dono dos dados
`users`	Criador, responsável, autor de filhos
`permissions`	Catálogo `module = 'tarefas'`
`user_permissions`	Flags por usuário (`allowed` 0/1)
`logs`	Log global (`module = 'tarefas'`)
`clients`	Indireto via `projects.client_id`

6. Relacionamentos

6.1 Matriz de FKs

De	Para	Coluna	ON DELETE
`tasks`	`tenants`	`tenant_id`	RESTRICT
`tasks`	`users`	`assigned_to`	SET NULL
`tasks`	`users`	`created_by`	CASCADE
`task_steps`	`tasks`	`task_id`	CASCADE
`task_steps`	`users`	`created_by`	CASCADE
`task_documents`	`tasks`	`task_id`	CASCADE
`task_documents`	`users`	`uploaded_by`	CASCADE
`task_activity_flow_steps`	`tasks`	`task_id`	CASCADE
`task_activity_flow_steps`	`users`	`created_by`	CASCADE
`task_comments`	`tasks`	`task_id`	CASCADE
`task_comments`	`users`	`user_id`	CASCADE
`task_history`	`tasks`	`task_id`	CASCADE
`projects`	`tenants`	`tenant_id`	RESTRICT
`projects`	`clients`	`client_id`	SET NULL
`tenant_modules`	`tenants`	`tenant_id`	CASCADE

6.2 Relacionamento lógico (sem FK)

projects.name  ←→  tasks.project
(mesmo tenant_id)

Recomendação para o novo projeto: migrar para tasks.project_id INT NULL FK → projects(id) ON DELETE SET NULL.

6.3 Cardinalidade

Relação	Cardinalidade
Tenant → Tasks	1:N
User → Tasks (criador)	1:N
User → Tasks (responsável)	1:N (nullable)
Task → Steps	1:N
Task → Documents	1:N (máx. 3 na regra de negócio)
Task → Flow steps	1:N
Task → Comments	1:N
Task → History	1:N
Project ↔ Task	N:N lógico via nome (hoje); ideal 1:N via FK

7. Enums e catálogos

7.1 Status da tarefa

Valor	Label listagem	Label Kanban	Visível no Kanban	`completed_at`
`pending`	Pendente	Pendente	Sim	`null`
`started`	Iniciada	Em andamento	Sim	`null`
`completed`	Concluída	Feito	Sim	preenchido
`cancelled`	Cancelada	—	Não	`null`

previous_status: ao ir para completed, grava o status anterior; ao sair de completed para outro destino, zera.

7.2 Prioridade

Valor	Label	Default
`low`	Baixa
`medium`	Média	Sim
`high`	Alta

7.3 Filtros de vencimento (listagem)

Código API	Significado SQL
`overdue`	`due_date < hoje` e status ≠ completed
`today`	`due_date = hoje` e status ≠ completed
`week`	`due_date` entre hoje e +7 dias e status ≠ completed
`no_due`	`due_date IS NULL`

7.4 Badges de prazo (UI)

Condição	Badge
Sem prazo	Sem prazo
Vencida	Vencida
Hoje	Hoje
≤ 3 dias úteis	Curto prazo
≤ 7 dias	Na semana
> 7 dias	Longe

7.5 Status de projeto (satélite)

pending | in_progress | completed | paused

8. Permissões e visibilidade

8.1 Catálogo (`permissions.module = 'tarefas'`)

Flag	Descrição	Enforcement
`tarefas.read`	Ver páginas/APIs de leitura	Sim
`tarefas.read_own`	Ver apenas próprias	Sim (`TaskPolicy`)
`tarefas.read_all`	Ver todas do tenant	Sim
`tarefas.read_filtered`	Reservada	Hoje = `read_all`
`tarefas.create`	Criar (unitária + lote)	Sim
`tarefas.update`	Editar	Sim
`tarefas.delete`	Excluir	Sim
`tarefas.assign`	Atribuir a outro usuário	Sim
`tarefas.change_status`	Mudar status	Sim + exige role `super-admin`
`tarefas.steps.manage`	Passos	Sim
`tarefas.documents.manage`	Documentos	Sim
`tarefas.flow.manage`	Fluxo operacional	Sim
`tarefas.ai_summary.manage`	Resumo IA	Sim
`tarefas.block`	Bloquear	Não implementado

8.2 Defaults por role (módulo ON)

Role	Flags típicas
`admin` (WL)	`read`, `read_own`, `read_all`, `create`
`editor`	`read`, `read_own`, `create`
`super-admin`	Todas (bypass)

8.3 Matriz de visibilidade (`TaskPolicy`)

Flags do usuário	Resultado SQL
`read_all` OU `read_filtered`	Todas do `tenant_id`
Só `read_own`	`assigned_to = eu OR created_by = eu`
Nenhuma	`1 = 0` (vazio)

Aplicar em: listagem, detalhe, comentários, kanban, KPIs.

Atenção (legado): update/delete/steps/docs não revalidam read_own — só tenant_id + flag de mutação. No novo projeto, recomenda-se reaplicar a política também nas mutações.

8.4 Atribuição

Condição	Create	Update
Sem `tarefas.assign`	`assigned_to = Auth::id()`	Mantém anterior
Com `tarefas.assign`	Usuário ativo do mesmo tenant	Idem; inválido → 422

9. Regras de negócio

9.1 Título

Obrigatório
Mínimo 3 caracteres
Bulk: títulos < 3 são ignorados (sem erro)

9.2 Data de entrega (`due_date`)

Regra	Valor
Formato	`Y-m-d`
Fins de semana	Proibidos (sáb/dom)
Mínimo	3 dias úteis a partir de hoje
Máximo	+90 dias corridos
Bulk create	Sempre `null`

9.3 Status e conclusão

Evento	Efeito
Status → `completed`	`completed_at = NOW()`, grava `previous_status`
Status → outro (via change-status)	`previous_status = null`
Toggle Kanban (concluir)	`completed` ← status atual
Toggle Kanban (reabrir)	volta para `previous_status` ou `pending`

9.4 Bulk create

Campo	Valor fixo
Entrada	String com títulos separados por `;`
`status`	`pending`
`priority`	`medium`
`assigned_to`	criador
`due_date` / `project`	`null`

9.5 Documentos

Limite	Valor
Máx. por tarefa	3
Tamanho	10 MB
Extensões	`pdf, doc, docx, xls, xlsx, png, jpg, jpeg, txt, mp4, mov, avi, webm`

9.6 Passos e fluxo

Entidade	Título mín.	Ordem
Passo	2	Sem ordenação formal
Fluxo	2	`sort_order = MAX + 1`

9.7 Comentários

Mínimo 2 caracteres
Exige tarefas.read + visibilidade na tarefa
Detalhe lista últimas 50

9.8 Kanban

Regra	Valor
Colunas	pending, started, completed
Canceladas	Excluídas
Limite	200
Drag-and-drop	Não
Change status	Flag `change_status` e role `super-admin`

9.9 IA

Item	Detalhe
Pré-requisito	Flag + `OPENAI_API_KEY`
Entrada	Metadados da tarefa + anexos
Áudio	Transcrição (`mp4, webm, m4a, mp3, wav, ogg`)
PDF/imagem	Análise
TXT	Até 8000 chars
Saída	Resumo PT (objetivo, pontos, pendências, próximos passos)
Persistência	`ai_summary`, `ai_transcription`, `ai_summary_generated_at`

9.10 Invariantes obrigatórios

Toda tarefa tem tenant_id.
Mutações usam id + tenant_id.
Filhos CASCADE com a tarefa.
Módulo OFF → 403 + flags negadas.
Tenant plataforma sempre com módulo ON.
Sem FK com leads/clientes.
Exclusão de projeto bloqueada se houver tarefas com o mesmo nome.

10. Telas e capacidades UX

10.1 Inventário de telas

Tela	Arquivo origem	Gate	Função
Listagem	`tarefas.php`	módulo + `tarefas.read`	CRUD + detalhe (leitura) + IA
Kanban	`kanban.php`	módulo + `tarefas.read`	Board + detalhe editável + status (SA)
Dashboard Operação	`dashboard/_operacao.php`	módulo ON	KPIs / gráficos / últimas
Projetos	`projetos.php`	super-admin	CRUD projetos + link público
Status público	`projeto-status.php`	token público	Acompanhamento externo

Seção Operação:

Item	Visível se
Dashboard → aba Operação	`hasTasksModule`
Tarefas	módulo + `tarefas.read`
Kanban	módulo + `tarefas.read`

Busca global do header → tarefas.php?search=....

10.3 Listagem (`tarefas.php`)

Capacidade	Detalhe
Filtros	search, status, due
Paginação	page, per_page (5–50, default 10)
Layout	Tabela desktop + cards mobile
Ordenação	`due_date ASC` (com prazo primeiro), depois `created_at DESC`
Criar única	Formulário completo
Criar lote	Títulos separados por `;`
Detalhe	Read-only em passos/docs/fluxo; IA + comentários + histórico
Preview docs	Imagem, vídeo, PDF, link

10.4 Kanban (`kanban.php`)

Capacidade	Detalhe
Colunas	Pendente / Em andamento / Feito
Busca	Título/descrição
Mobile	Tabs + scroll snap
Atividades	Modal com toggle concluir/reabrir (super-admin)
Detalhe	Passos/docs/fluxo editáveis; sem IA

10.5 Dashboard Operação

Elemento	Conteúdo
KPIs	Concluídas, Pendentes, Iniciadas, Canceladas
Gráficos	Donut por status + barras de volume
Lista	Últimas tarefas (respeitando `TaskPolicy`)

10.6 Página pública do projeto

Elemento	Detalhe
Auth	Nenhuma (token)
Conteúdo	Progresso + lista de tarefas (sem canceladas)
Detalhe	Passos, fluxo, histórico, comentários, docs (metadados)
Branding	Identidade do tenant

11. Contrato de APIs

11.1 Guard comum

Todas as rotas de api/tarefas/**:

Autenticação
Módulo tasks ON
Tenant::requireId()
Flag específica + (quando leitura) TaskPolicy

11.2 CRUD e operações

Método	Endpoint	Permissão	Função
GET	`/api/tarefas`	`tarefas.read`	Listagem
POST	`/api/tarefas`	`tarefas.create`	Criar
POST	`/api/tarefas/update`	`tarefas.update`	Atualizar
POST	`/api/tarefas/delete`	`tarefas.delete`	Excluir
POST	`/api/tarefas/bulk-create`	`tarefas.create`	Lote
POST	`/api/tarefas/change-status`	`change_status` + super-admin	Status
GET	`/api/kanban`	`tarefas.read`	Board

GET `/api/tarefas` — query

Param	Tipo	Default	Notas
`page`	int	1	≥ 1
`per_page`	int	10	5–50
`search`	string		title/description LIKE
`status`	enum		pending/started/completed/cancelled
`due`	enum		overdue/today/week/no_due

POST `/api/tarefas` — body

Campo	Obrigatório	Notas
`title`	Sim	≥ 3
`description`	Não
`project`	Não	string nome
`status`	Não	default pending
`priority`	Não	default medium
`due_date`	Não	regras de janela
`assigned_to`	Não	só com assign

POST `/api/tarefas/bulk-create` — body

{ "items": "Tarefa A; Tarefa B; Tarefa C" }

POST `/api/tarefas/change-status` — body

{ "id": 123, "status": "completed" }

11.3 Detalhes

Endpoint	Permissão	Body/Query	Função
`GET/POST detalhes/show`	`read` + visibility	`id`	Payload completo + `can_manage_*`
`detalhes/step-create`	`steps.manage`	`task_id`, `title`	Novo passo
`detalhes/step-toggle`	`steps.manage`	`id`, `is_done`	Toggle
`detalhes/document-upload`	`documents.manage`	multipart `task_id`, `document`	Upload
`detalhes/flow-step-create`	`flow.manage`	`task_id`, `title`	Nova etapa
`detalhes/flow-step-delete`	`flow.manage`	`id`	Remover etapa
`detalhes/comment-create`	`read` + visibility	`task_id`, `comment`	Comentário
`detalhes/ai-summary`	`ai_summary.manage`	`task_id`	Gerar resumo

11.4 Payload sugerido do detalhe

{
  "task": { "...campos de tasks...", "assigned_name": "..." },
  "steps": [],
  "documents": [],
  "flow_steps": [],
  "comments": [],
  "history": [],
  "can_manage_steps": true,
  "can_manage_documents": true,
  "can_manage_flow": true,
  "can_manage_ai_summary": false
}

11.5 Meta da listagem

{
  "can_assign": true,
  "assignable_users": [{ "id": 1, "name": "..." }],
  "current_user_id": 1,
  "pagination": { "page": 1, "per_page": 10, "total": 42 }
}

11.6 Dashboard / gestão

Endpoint	Gate	Função
`GET /api/dashboard/kpis`	módulo + TaskPolicy	Contagens + últimas
`GET /api/gestao/kpis`	platform admin	KPIs cross-tenant

11.7 Projetos públicos

Endpoint	Auth	Função
`GET /api/projetos/public/show?token=`	Público	Projeto + tarefas
`GET /api/projetos/public/task?token=&task_id=`	Público	Detalhe da tarefa

12. Armazenamento de arquivos

Item	Valor
Diretório	`public/uploads/task-documents/`
Nome físico	`task-{taskId}-{random}.{ext}`
Metadados	`original_name`, `file_name`, `file_path`, `mime_type`, `file_size`
Exclusão	CASCADE no DB; garantir limpeza física no novo projeto

13. Auditoria e logs

13.1 Histórico da tarefa (`task_history.action`)

Action	Quando
`created_task`	Create / bulk item
`updated_task`	Update
`changed_task_status`	Change status
`created_task_step`	Novo passo
`updated_task_step`	Toggle passo
`uploaded_task_document`	Upload
`created_task_activity_flow_step`	Nova etapa fluxo
`deleted_task_activity_flow_step`	Remove etapa fluxo
`created_task_comment`	Comentário

13.2 Log global (`logs.module = 'tarefas'`)

Action	Endpoint
`created_task`	create
`bulk_created_tasks`	bulk
`updated_task`	update
`deleted_task`	delete
`changed_task_status`	change-status
`created_task_step` / `updated_task_step`	steps
`uploaded_task_document`	upload
`created_task_activity_flow_step` / `deleted_task_activity_flow_step`	flow
`generated_task_ai_summary`	IA

14. Integrações

Integração	Como
Dashboard	Aba Operação + KPIs
Gestão da plataforma	Totais cross-tenant
Projetos	Contagem, bloqueio exclusão, link público
Permissões	Grupo do módulo `tarefas`
White label	Toggle `tasks` + seed admin
WhatsApp	Script diário: pendentes com vencimento ≤ 3 dias úteis
OpenAI	Resumo de tarefa
Navbar	Busca → listagem
Leads/Comercial	Sem integração estrutural

15. Fluxos principais

15.1 Navegação

flowchart LR
  subgraph Operacao
    T[Listagem]
    K[Kanban]
    D[Dashboard]
  end

  T --> CRUD[Criar / Editar / Excluir]
  T --> DetL[Detalhe leitura + IA + comentarios]
  K --> Board[Board por status]
  Board --> DetK[Detalhe editavel]
  Board --> SA[Toggle status super-admin]
  D --> KPI[KPIs]

  P[Projetos] -.->|nome| T
  P --> Pub[Link publico]

15.2 Ciclo de status

stateDiagram-v2
  [*] --> pending
  pending --> started
  pending --> completed
  pending --> cancelled
  started --> completed
  started --> cancelled
  started --> pending
  completed --> pending: reabrir via previous_status
  completed --> started: reabrir
  cancelled --> pending
  cancelled --> started

15.3 Três conceitos no detalhe

flowchart TB
  Task[Tarefa]
  Timeline[Timeline UI derivada do status]
  Steps[Passos / checklist task_steps]
  Flow[Fluxo operacional task_activity_flow_steps]
  Docs[Documentos task_documents]
  Comments[Comentarios]
  History[Historico]

  Task --> Timeline
  Task --> Steps
  Task --> Flow
  Task --> Docs
  Task --> Comments
  Task --> History

16. Sugestões para reimplementação

Ao refazer em outro projeto, recomenda-se:

Tema	Melhoria
Projeto	Usar `project_id` FK em vez de string
Kanban	Drag-and-drop com optimistic UI
Detalhe	Unificar capacidades (IA + edição) numa única tela/modal
Visibilidade	Reaplicar `read_own` também em mutações
`read_filtered`	Definir regra real ou remover a flag
`block`	Implementar ou remover
Arquivos	Apagar do disco ao deletar registro/tarefa
Rename projeto	Propagar ou bloquear rename com tarefas
Change-status	Decidir se é só admin/SA ou qualquer um com flag
API	REST consistente (PATCH/DELETE) + paginação cursor se escala

16.1 Stack mínima sugerida (independente de linguagem)

Auth + tenant context
Tabela de módulos por tenant
RBAC por flags
Policy de visibilidade
Storage de arquivos
Job/script opcional de lembretes
Provider de IA opcional (feature flag)

16.2 Ordem de implementação sugerida

Schema + migrations (tasks + filhos + tenant_modules)
Permissions seed
CRUD + TaskPolicy
Listagem + filtros + paginação
Detalhe (steps → docs → flow → comments → history)
Kanban
Dashboard KPIs
Bulk create
Projetos + link público (se necessário)
IA
Notificações (WhatsApp/e-mail)

17. Critérios de aceitação

Apêndice A — Referência no Organiza (origem)

Área	Caminhos
Páginas	`public/tarefas.php`, `public/kanban.php`, `public/projetos.php`, `public/projeto-status.php`, `public/dashboard/_operacao.php`
APIs	`api/tarefas/**`, `api/kanban/index.php`
Core	`app/Core/TaskPolicy.php`, `TaskHistory.php`, `ProjectPublicLink.php`
Schema	`database/schema.sql` (blocos `tasks*`, `projects`, `tenant_modules`)
Regras	`.cursor/rules/tarefas-negocio.mdc`

Apêndice B — Checklist de portabilidade

Copiar/adaptar nesta ordem:

DDL das 6 tabelas de tarefa + índice/tenant_modules
Seed das 14 permissions
Policy de leitura (own/all)
Validador de due_date (dias úteis)
Endpoints CRUD + detalhes
UI listagem + kanban + detalhe
Storage de documentos
(Opcional) IA, WhatsApp, projetos públicos

Sumário​

1. Visão geral​

Ciclo operacional​

Princípios​

2. Escopo​

2.1 Dentro do escopo​

2.2 Fora do escopo (no Organiza atual)​

3. Glossário​

4. Arquitetura e multi-tenant​

4.1 Gate do módulo​

4.2 Camadas de enforcement​

4.3 Isolamento de dados​

5. Modelo de dados​

5.1 Mapa de tabelas do módulo​

5.2 Diagrama ER​

5.3 Tabela tasks​

5.4 Tabela task_steps (checklist)​

5.5 Tabela task_documents​

5.6 Tabela task_activity_flow_steps​

5.7 Tabela task_comments​

5.8 Tabela task_history​

5.9 Tabela projects (satélite)​

5.10 Tabelas de suporte (já existentes no sistema)​

6. Relacionamentos​

6.1 Matriz de FKs​

6.2 Relacionamento lógico (sem FK)​

6.3 Cardinalidade​

7. Enums e catálogos​

7.1 Status da tarefa​

7.2 Prioridade​

7.3 Filtros de vencimento (listagem)​

7.4 Badges de prazo (UI)​

7.5 Status de projeto (satélite)​

8. Permissões e visibilidade​

8.1 Catálogo (permissions.module = 'tarefas')​

8.2 Defaults por role (módulo ON)​

8.3 Matriz de visibilidade (TaskPolicy)​

8.4 Atribuição​

9. Regras de negócio​

9.1 Título​

9.2 Data de entrega (due_date)​

9.3 Status e conclusão​

9.4 Bulk create​

9.5 Documentos​

9.6 Passos e fluxo​

9.7 Comentários​

9.8 Kanban​

9.9 IA​

9.10 Invariantes obrigatórios​

10. Telas e capacidades UX​

10.1 Inventário de telas​

10.2 Menu​

10.3 Listagem (tarefas.php)​

10.4 Kanban (kanban.php)​

10.5 Dashboard Operação​

10.6 Página pública do projeto​

11. Contrato de APIs​

11.1 Guard comum​

11.2 CRUD e operações​

GET /api/tarefas — query​

POST /api/tarefas — body​

POST /api/tarefas/bulk-create — body​

POST /api/tarefas/change-status — body​

11.3 Detalhes​

11.4 Payload sugerido do detalhe​

11.5 Meta da listagem​

11.6 Dashboard / gestão​

11.7 Projetos públicos​

12. Armazenamento de arquivos​

13. Auditoria e logs​

13.1 Histórico da tarefa (task_history.action)​

13.2 Log global (logs.module = 'tarefas')​

14. Integrações​

15. Fluxos principais​

15.1 Navegação​

15.2 Ciclo de status​

15.3 Três conceitos no detalhe​

16. Sugestões para reimplementação​

16.1 Stack mínima sugerida (independente de linguagem)​

16.2 Ordem de implementação sugerida​