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.

Endpoints HTTP atuais no AMPLIA: api/endpoints.md. OpenAPI: api/openapi.yaml.

---

Sumário

1. Visão geral
2. Escopo
3. Glossário
4. Arquitetura e multi-tenant
5. Modelo de dados
6. Relacionamentos
7. Enums e catálogos
8. Permissões e visibilidade
9. Regras de negócio
10. Telas e capacidades UX
11. Contrato de APIs
12. Armazenamento de arquivos
13. Auditoria e logs
14. Integrações
15. Fluxos principais
16. Sugestões para reimplementação
17. 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

1. Toda query/mutação filtra por tenant_id da sessão.
2. Filhos (steps, docs, flow, comments, history) não têm tenant_id próprio — herdam via task_id + CASCADE.
3. 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

1. Toda tarefa tem tenant_id.
2. Mutações usam id + tenant_id.
3. Filhos CASCADE com a tarefa.
4. Módulo OFF → 403 + flags negadas.
5. Tenant plataforma sempre com módulo ON.
6. Sem FK com leads/clientes.
7. 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

10.2 Menu

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/**:

1. Autenticação
2. Módulo tasks ON
3. Tenant::requireId()
4. 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

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

---

17. Critérios de aceitação

• Módulo OFF: menu some, APIs 403, flags tarefas.* negadas
• Módulo ON: tarefas.read acessa listagem e kanban
• read_own restringe listagem/detalhe/KPIs
• Create valida título (≥3) e due_date (dias úteis + janela)
• Sem assign, responsável = criador
• Bulk gera só títulos válidos (pending/medium/criador)
• Comentários respeitam visibilidade
• Steps/docs/fluxo exigem flags *.manage
• Upload: máx. 3 arquivos, 10 MB, extensões permitidas
• IA exige flag + chave e persiste ai_*
• Kanban oculta canceladas; change-status só para perfil autorizado
• Excluir projeto com tarefas vinculadas é bloqueado
• Link público mostra progresso sem login
• Excluir tarefa remove filhos (CASCADE)
• Dashboard reflete KPIs coerentes com a visibilidade

---

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:

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