feat: bootstrap project

2026-05-31 20:22:50 +01:00
commit 66581ef584
65 changed files with 7915 additions and 0 deletions
@@ -0,0 +1,33 @@
+# US02 - Listar Beneficiários (Admin)
+
+**Como** Administrador do RefoodOne
+**Quero** visualizar a lista de todos os beneficiários registados no sistema
+**Para** poder consultar os seus dados e gerir a atribuição de apoio alimentar.
+
+## Descrição do Fluxo
+O Administrador acede ao menu "Admin" -> "Beneficiários", onde lhe é apresentada uma tabela com a listagem de todos os beneficiários registados. A listagem permite pesquisar e filtrar os beneficiários de forma rápida.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Tabela de Beneficiários**: Deve conter as seguintes colunas:
+
+  - **Número** (Número de beneficiário)
+  - **Nome** (Nome do beneficiário)
+  - **Nº Pessoas** (Número de pessoas do agregado familiar)
+  - **Estado** (Ativo / Inativo)
+  - **Ações** (Botões para Editar/Inativar/Ver Detalhes)
+- **Filtros e Pesquisa**:
+  - Barra de pesquisa por Nome ou número
+  - Filtro por Estado (Todos, Ativos, Inativos).
+- **Botão "Novo Beneficiário"**: Um botão destacado (ex: cor primária/verde) posicionado no topo da página para criar um novo beneficiário.
+- **Paginação**: Caso existam muitos beneficiários, a tabela deve ser paginada (ex: 15 por página).
+
+### 2. Comportamento e Regras de Negócio
+- Apenas utilizadores com a função **Admin** podem aceder a esta página.
+- Se um utilizador sem permissões tentar aceder, o sistema deve apresentar uma página de erro 403 (Acesso Negado) ou redirecionar para a página inicial com mensagem de erro.
+- A listagem deve ser ordenada alfabeticamente por Nome por defeito.
+
+### 3. Integração de Dados / Segurança
+- Os dados devem ser lidos diretamente da tabela de beneficiários da base de dados SQLite.
+- A consulta à base de dados deve ser executada exclusivamente no servidor (`+page.server.ts`).
@@ -0,0 +1,37 @@
+# US03 - Detalhe e Edição de Beneficiário (Admin)
+
+**Como** Administrador do RefoodOne
+**Quero** visualizar, criar e editar as informações de um beneficiário específico
+**Para** manter os dados dos beneficiários atualizados no sistema.
+
+## Descrição do Fluxo
+Este ecrã serve dois propósitos:
+1. **Criação**: Acedido através do botão "Novo Beneficiário" na listagem (US02), abrindo o formulário vazio para preenchimento.
+2. **Edição/Visualização**: Acedido através do botão de ação "Editar" na listagem (US02), abrindo o formulário pré-preenchido com os dados do beneficiário selecionado.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Campos do Formulário**:
+  - **Número** (obrigatório, numérico único - identificador do beneficiário no sistema)
+  - **Nome** (obrigatório, texto)
+  - **Contacto** (obrigatório, número de telefone/telemóvel válido)
+  - **Nº Pessoas do Agregado** (obrigatório, numérico, mínimo 1)
+  - **Observações** (opcional, área de texto livre para notas adicionais)
+  - **Estado** (Ativo / Inativo - apenas na edição)
+- **Botões de Ação**:
+  - **Guardar** (submete o formulário e guarda os dados)
+  - **Cancelar** (volta para a listagem sem guardar alterações)
+
+### 2. Comportamento e Regras de Negócio
+- Apenas utilizadores com a função **Admin** podem aceder/gravar neste ecrã.
+- **Validações**:
+  - O campo **Número** deve ser único na base de dados. Se o Administrador tentar guardar um número já existente, o sistema deve exibir um aviso claro em PT-PT.
+  - Todos os campos obrigatórios devem ser validados antes de permitir guardar.
+- **Redirecionamento**:
+  - Após guardar com sucesso (inserir ou atualizar), o sistema deve redirecionar o utilizador de volta para a listagem de beneficiários (US02) com uma mensagem de sucesso (ex: *"Beneficiário guardado com sucesso"*).
+  - Clicar em Cancelar deve redirecionar de volta para a listagem (US02) sem efetuar qualquer alteração.
+
+### 3. Integração de Dados / Segurança
+- As operações de escrita (INSERT/UPDATE) devem ser efetuadas de forma segura na base de dados SQLite através do Drizzle ORM.
+- O processamento do formulário deve ser feito inteiramente no servidor (`+page.server.ts` actions).
@@ -0,0 +1,32 @@
+# US04 - Listar Turnos (Admin)
+
+**Como** Administrador ou Gestor de Turnos do RefoodOne
+**Quero** visualizar a lista de todos os turnos de entregas registados no sistema
+**Para** consultar o seu horário atual e os dias em que são realizados.
+
+## Descrição do Fluxo
+O utilizador acede ao menu de administração correspondente aos "Turnos", onde lhe é apresentada uma tabela com os turnos configurados no sistema (ex: T1, T2, T3), indicando os seus horários e os dias da semana em que ocorrem.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Tabela de Turnos**: Deve conter as seguintes colunas:
+  - **Identificador** (ex: T1, T2, T3)
+  - **Horário** (ex: 14h30 - 16h30)
+  - **Duração** (ex: 2h)
+  - **Dias de Funcionamento** (ex: Terças e Quintas)
+  - **Ações** (Botão para Editar)
+- **Idioma**: Todos os textos e cabeçalhos devem estar em PT-PT.
+
+### 2. Comportamento e Regras de Negócio
+- Apenas utilizadores com as funções de **Admin** ou **Gestor de Turnos** podem aceder a esta listagem.
+- Por defeito, o sistema deve apresentar os turnos configurados atualmente:
+  - **T1**: 14h30 - 16h30
+  - **T2**: 16h30 - 18h30
+  - **T3**: 18h30 - 20h30
+- Por defeito, os dias de funcionamento são as **3ªs feiras (Terças)** e **5ªs feiras (Quintas)**.
+- A listagem deve ser ordenada por ordem cronológica de horário de início.
+
+### 3. Integração de Dados / Segurança
+- Os dados devem ser lidos da base de dados SQLite através das tabelas de configuração/turnos do sistema.
+- A consulta à base de dados deve ser executada exclusivamente no servidor (`+page.server.ts`).
@@ -0,0 +1,34 @@
+# US05 - Editar Horário e Dias de Turno (Admin)
+
+**Como** Administrador ou Gestor de Turnos do RefoodOne
+**Quero** editar o horário (horas de início e fim) e os dias da semana de um turno específico
+**Para** adaptar o funcionamento das entregas conforme a disponibilidade dos voluntários e as necessidades da Refood PdN.
+
+## Descrição do Fluxo
+O utilizador clica no botão "Editar" de um turno específico na listagem de turnos (US04). É apresentado um formulário pré-preenchido onde pode alterar a hora de início, a hora de fim e selecionar/deselecionar os dias da semana em que o turno é realizado.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Campos do Formulário**:
+  - **Identificador** (Apenas leitura/desativado, ex: "T1")
+  - **Hora de Início** (Obrigatório, seletor de tempo no formato HH:MM)
+  - **Hora de Fim** (Obrigatório, seletor de tempo no formato HH:MM)
+  - **Dias da Semana** (Obrigatório, checkboxes permitindo selecionar múltiplos dias, ex: Segunda a Domingo)
+- **Botões de Ação**:
+  - **Guardar** (Submete o formulário e grava as alterações)
+  - **Cancelar** (Volta para a listagem sem guardar)
+
+### 2. Comportamento e Regras de Negócio
+- Apenas utilizadores com as funções de **Admin** ou **Gestor de Turnos** podem aceder a este ecrã e guardar alterações.
+- **Validações**:
+  - A hora de fim deve ser posterior à hora de início.
+  - A duração configurada deve respeitar as regras do sistema (ex: 2 horas por turno por defeito, ou emitir um aviso/validação caso não seja).
+  - Pelo menos um dia da semana deve ser selecionado (não é permitido ter um turno ativo sem dias associados).
+- **Redirecionamento**:
+  - Após guardar com sucesso, redirecionar para a listagem de turnos (US04) com uma mensagem de sucesso em PT-PT (ex: *"Horário do turno guardado com sucesso"*).
+  - Clicar em Cancelar redireciona de volta para a listagem (US04) sem efetuar qualquer alteração.
+
+### 3. Integração de Dados / Segurança
+- As alterações de horário e dias devem ser guardadas com segurança na base de dados SQLite através do Drizzle ORM.
+- O processamento da ação do formulário deve ocorrer no servidor (`+page.server.ts` actions).
@@ -0,0 +1,36 @@
+# US06 - Inicialização (Bootstrap) de Turnos
+
+**Como** Sistema do RefoodOne
+**Quero** inicializar a base de dados com os turnos predefinidos (T1, T2 e T3)
+**Para** garantir que a aplicação começa a funcionar com uma configuração base válida e sem necessidade de introdução manual de dados.
+
+## Descrição do Fluxo
+Este é um processo automatizado executado pelo sistema (ex: através de um script de *seeding* ou na inicialização da base de dados). O sistema verifica se a tabela de turnos está vazia e, caso esteja, insere os três turnos base com os horários e dias da semana padrão.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- Não aplicável (processo de sistema em segundo plano).
+
+### 2. Comportamento e Regras de Negócio
+- **Verificação de Existência**: O bootstrap apenas deve ser executado se a tabela de turnos na base de dados SQLite estiver completamente vazia. Se já existirem dados, o processo não deve fazer nada (para evitar sobrescrever alterações manuais feitas pelo Administrador).
+- **Dados Padrão a Inserir**:
+  - **Turno T1**:
+    - Código/Identificador: `T1`
+    - Hora de Início: `14:30`
+    - Hora de Fim: `16:30`
+    - Dias da Semana: Terça-feira (3ªf) e Quinta-feira (5ªf)
+  - **Turno T2**:
+    - Código/Identificador: `T2`
+    - Hora de Início: `16:30`
+    - Hora de Fim: `18:30`
+    - Dias da Semana: Terça-feira (3ªf) e Quinta-feira (5ªf)
+  - **Turno T3**:
+    - Código/Identificador: `T3`
+    - Hora de Início: `18:30`
+    - Hora de Fim: `20:30`
+    - Dias da Semana: Terça-feira (3ªf) e Quinta-feira (5ªf)
+
+### 3. Integração de Dados / Segurança
+- A inserção dos dados deve ser feita de forma segura utilizando o Drizzle ORM num script de seed (`seed.ts` ou semelhante) ou num mecanismo executado durante o arranque do servidor.
+- Os dias da semana devem ser armazenados num formato estruturado (ex: JSON array ou tabela de junção) para fácil manipulação pelas US04 e US05.