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,17 @@
+## Developer Profile
+
+- Senior software engineer / IT architect (+30 years experience)
+- Strong backend and system design experience
+- Limited hands-on experience with:
+  - SvelteKit
+  - FastAPI
+  - PostgreSQL (modern usage patterns)
+  - TypeScript ecosystems
+
+## Implications for AI behavior
+
+- Prefer explicit, simple solutions
+- Avoid assuming deep framework knowledge
+- Provide minimal but correct explanations when needed
+- Avoid over-abstracted patterns
+- Prioritize clarity over framework idioms
@@ -0,0 +1,31 @@
+This is an application to manage Refood volunteers, routes and beneficiaries. 
+Project main concepts
+
+* Users - The users of the application
+* Roles - The roles of the users, there will be 3 main roles:
+    1. Admin - Can manage users, volunteersshifts and beneficiaries
+    2. Shift manager - Can manage volunteers and benficiaries
+    3. Volunteer - Record food delivery to beneficiaries     
+
+* Shifts - The shifts are time slots where the food is delivered to beneficiaries
+    
+Project name is "RefoodOne" and should be visible in the application, in a non intrusive way.
+The logo is the file Refood Rotas-v2.png and use the brand refood colors and fonts in the app theme.
+
+All the interface should be in PT-PT
+
+Has 1 login screen with user and password 
+Main modules
+* Admin (require admin role)
+    * User
+    * Shifts
+    * Volunteers
+    * Beneficiaries
+
+* Deliveries
+    * Track delivery
+    * List deliveries
+
+
+
+
@@ -0,0 +1,22 @@
+# USXX - [Título Curto e Descritivo da User Story]
+
+**Como** [tipo de utilizador / perfil]
+**Quero** [desejo / ação que quer realizar]
+**Para** [benefício / valor de negócio gerado]
+
+## Descrição do Fluxo
+[Breve descrição de como o utilizador interage com esta funcionalidade ou qual o fluxo principal.]
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- [ ] Detalhes visuais, ecrãs, campos e botões em PT-PT.
+- [ ] Validações de formulários (campos obrigatórios, formatos específicos).
+
+### 2. Comportamento e Regras de Negócio
+- [ ] Regras que o sistema deve cumprir.
+- [ ] Fluxos alternativos ou tratamento de erros.
+
+### 3. Integração de Dados / Segurança
+- [ ] Que dados devem ser guardados ou alterados na base de dados SQLite.
+- [ ] Permissões de acesso (quem pode aceder/realizar esta ação).
@@ -0,0 +1,19 @@
+# US00 - Inicialização do Utilizador Administrador (Seed/Bootstrap)
+
+**Como** Sistema RefoodOne
+**Quero** garantir que existe pelo menos um utilizador Administrador inicial na base de dados aquando do primeiro arranque
+**Para** permitir que a equipa possa fazer login e começar a gerir o sistema.
+
+## Descrição do Fluxo
+Durante a inicialização da base de dados (ou execução das migrações/seed), o sistema deve verificar se já existe algum utilizador registado. Se a base de dados estiver vazia, deve criar automaticamente o utilizador administrador inicial com credenciais pré-definidas.
+
+## Critérios de Aceitação
+
+### 1. Utilizador Administrador Inicial
+- **E-mail / Username**: `refoodpdn`
+- **Palavra-passe**: `rpdn!2512` (deve ser guardada de forma segura na base de dados usando hash argon2 ou bcrypt)
+- **Perfil (Role)**: `admin`
+
+### 2. Comportamento e Regras de Negócio
+- O bootstrap deve ocorrer apenas uma vez. Se o utilizador `refoodpdn` já existir, a rotina não deve duplicar o registo nem reescrever a palavra-passe caso esta tenha sido alterada pelo utilizador.
+- O processo deve ser automático ao correr as migrações/inicialização do servidor ou através de um script de sementeira (seed) dedicado.
@@ -0,0 +1,27 @@
+# US01 - Autenticação (Login)
+
+**Como** utilizador do RefoodOne (Administrador, Gestor de Turno ou Voluntário)
+**Quero** introduzir as minhas credenciais (nome de utilizador/email e palavra-passe)
+**Para** aceder às funcionalidades específicas do meu perfil/função no sistema.
+
+## Critérios de Aceitação
+
+### 1. Interface de Login (PT-PT)
+- Página limpa com o logótipo do Refood e o nome "RefoodOne" visível de forma não intrusiva.
+- Campos de entrada:
+  - **E-mail** (obrigatório)
+  - **Palavra-passe** (obrigatório, com opção de ocultar/mostrar a palavra-passe)
+- Botão de ação: **Entrar**
+
+### 2. Validação e Segurança
+- O sistema deve validar as credenciais contra a base de dados SQLite.
+- A palavra-passe deve ser verificada de forma segura (usando hash bcrypt/argon2 conforme definido em `.clinrules`).
+- Se as credenciais estiverem incorretas:
+  - Mostrar uma mensagem de erro em PT-PT: *"Utilizador ou palavra-passe incorretos."*
+  - Não revelar qual dos campos está incorreto por motivos de segurança.
+- Cookies de sessão seguros devem ser utilizados após o login com sucesso.
+
+### 3. Redirecionamento por Perfil (Role)
+Após o login com sucesso, o utilizador deve ser redirecionado:
+- **Administrador**: Redirecionar para a página de gestão de turnos
+- **Voluntário**: Redirecionar diretamente para o ecrã de registo/entrega de comida (Entregas).
@@ -0,0 +1,29 @@
+# US07 - Agrupamento do Menu de Navegação (Menu Gestão)
+
+**Como** Utilizador autenticado do RefoodOne
+**Quero** que as opções "Beneficiários", "Turnos" e "Entregas" sejam agrupadas num submenu sob um menu principal chamado "Gestão"
+**Para** melhorar a organização do cabeçalho de navegação e tornar a interface mais limpa e intuitiva.
+
+## Descrição do Fluxo
+Ao fazer login na aplicação, o utilizador visualiza um cabeçalho de navegação (navbar) simplificado. Em vez de ter os links principais expostos diretamente, é exibido um item de menu interativo chamado **Gestão**. Ao clicar ou passar o cursor sobre este menu, abre-se um dropdown contendo as opções autorizadas para o perfil do utilizador.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Menu Gestão**: Deve ser exibido como um menu dropdown na barra de navegação superior, com a etiqueta "Gestão" em PT-PT.
+- **Opções do Submenu**: O dropdown deve conter as seguintes opções (quando aplicável ao perfil):
+  - **Beneficiários**
+  - **Turnos**
+  - **Entregas**
+- **Estilo**: O dropdown deve seguir a estética Bootstrap 5, com comportamento responsivo (fechamento automático ao clicar fora e suporte a ecrãs táteis/mobile).
+
+### 2. Comportamento e Regras de Negócio
+- As opções visíveis no submenu devem respeitar rigorosamente as permissões de cada perfil de utilizador:
+  - **Administrador (Admin)**: Visualiza todas as opções no submenu (**Beneficiários**, **Turnos**, **Entregas**).
+  - **Gestor de Turno (Shift Manager)**: Visualiza as opções permitidas (**Turnos**, **Entregas** e **Beneficiários** conforme permissões de gestão).
+  - **Voluntário (Volunteer)**: Visualiza apenas a opção **Entregas** (ou redirecionado diretamente).
+- O submenu só deve ser visível se o utilizador estiver autenticado.
+
+### 3. Integração de Dados / Segurança
+- O controlo de visibilidade dos links do submenu deve basear-se no objeto `data.user` carregado pelo layout principal (`+layout.svelte`).
+- A proteção de rotas no servidor (`hooks.server.ts`) deve continuar a validar e bloquear acessos diretos caso o utilizador digite o URL manualmente.
@@ -0,0 +1,19 @@
+# US08 - Modelo de Dados de Entregas
+
+**Como** Sistema RefoodOne
+**Quero** definir a estrutura e modelo de dados para o registo das entregas de cabazes aos beneficiários
+**Para** garantir a integridade dos dados e o relacionamento correto entre as entregas, os beneficiários e os turnos.
+
+## Critérios de Aceitação
+
+### 1. Estrutura da Tabela `deliveries`
+A tabela de entregas na base de dados SQLite deve conter os seguintes campos:
+- **`id`**: Texto (Primary Key, UUID gerado automaticamente, não nulo).
+- **`beneficiary_id`**: Texto (não nulo). Chave estrangeira que referencia a tabela `beneficiaries.id`.
+- **`shift_id`**: Texto (não nulo). Chave estrangeira que referencia a tabela `shifts.id`.
+- **`date`**: Texto (não nulo, formato 'YYYY-MM-DD'). Representa o dia em que a entrega foi efetuada.
+- **`created_at`**: Inteiro (não nulo, timestamp). Guarda a data e hora do registo do sistema.
+
+### 2. Integridade Referencial e Comportamento
+- **Chave Estrangeira de Beneficiário**: A coluna `beneficiary_id` deve referenciar `beneficiaries(id)`. Deve incluir uma regra de eliminação em cascata (`ON DELETE CASCADE`), de modo a que se um beneficiário for removido, o seu histórico de entregas seja automaticamente apagado.
+- **Chave Estrangeira de Turno**: A coluna `shift_id` deve referenciar `shifts(id)`. Deve incluir uma regra de eliminação em cascata (`ON DELETE CASCADE`), de modo a que se um turno for removido do sistema, os registos de entrega a ele associados sejam removidos.
@@ -0,0 +1,40 @@
+# US09 - Interface de Registo de Entregas
+
+**Como** Voluntário ou Administrador do RefoodOne
+**Quero** um ecrã com botões grandes para cada beneficiário ativo e um popup de confirmação
+**Para** registar de forma rápida e tátil as entregas de cabazes em dispositivos tablet.
+
+## Descrição do Fluxo
+O voluntário acede ao menu "Entregas". O ecrã apresenta uma grelha de botões táteis correspondentes a todos os beneficiários ativos. Ao tocar no botão de um beneficiário (ex: "#124"), abre-se um popup de confirmação exibindo os dados principais do beneficiário (Nome e Nº de Pessoas do Agregado). Ao clicar em "Confirmar", o sistema grava a entrega associando o turno ativo e a data corrente, e fecha o popup.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Ecrã de Grelha (Grid)**:
+  - Apresenta botões organizados em grelha (vários por linha dependendo da resolução).
+  - Cada botão corresponde a um **beneficiário ativo**.
+  - O rótulo (label) do botão deve ser o **número do beneficiário** em destaque.
+  - Os botões devem ser dimensionados para facilitar o toque com o dedo (design tátil ideal para tablets).
+- **Popup de Confirmação (Modal)**:
+  - Disparado ao clicar no botão de um beneficiário.
+  - Deve mostrar em destaque:
+    - **Nome do beneficiário**
+    - **Nº de pessoas do agregado familiar** (do registo do beneficiário)
+  - Botões de Ação no popup:
+    - **Confirmar** (submete o registo de entrega, cor verde)
+    - **Cancelar** (fecha o popup sem registar, cor cinzenta)
+
+### 2. Comportamento e Regras de Negócio
+- Apenas beneficiários com estado **Ativo** devem ser exibidos na grelha.
+- **Prevenção de Duplicados (Desativação do Botão)**:
+  - Se um beneficiário já tiver uma entrega registada na data corrente (dia de hoje), o seu respetivo botão na grelha de entregas deve estar **desativado** (disabled).
+  - O botão desativado deve ter um aspeto visual distinto (ex: cor cinzenta ou verde-suave com um visto de "concluído") para indicar claramente que a entrega já foi efetuada no dia de hoje.
+- **Gravação Automática**:
+  - Ao confirmar, o sistema regista a entrega na base de dados (`deliveries`).
+  - A data de entrega é preenchida pelo servidor com a **data atual** (no formato YYYY-MM-DD).
+  - O turno é determinado automaticamente pelo servidor com base no **dia da semana e hora atual** em que o registo está a ser submetido (se cair fora do horário de funcionamento de qualquer turno, associa-se o turno padrão ou mais próximo).
+
+### 3. Integração de Dados / Segurança
+- O ecrã deve carregar os dados dos beneficiários e turnos no servidor (`+page.server.ts`).
+- A gravação deve ocorrer via SvelteKit Action (`POST` request) para garantir que a data e o turno sejam calculados e validados de forma segura no lado do servidor.
+- Apenas utilizadores autenticados podem aceder e registar entregas.
@@ -0,0 +1,26 @@
+# US10 - Nome do Beneficiário no Botão de Entrega
+
+**Como** Voluntário do RefoodOne
+**Quero** que o primeiro nome do beneficiário seja exibido por baixo do seu número no botão de registo de entrega
+**Para** facilitar a identificação visual rápida do beneficiário antes de clicar e reduzir a probabilidade de enganos no registo.
+
+## Descrição do Fluxo
+Ao aceder ao ecrã de registo de entregas ("Entregas"), o voluntário vê a grelha de botões táteis. Cada botão agora exibe não apenas o número do beneficiário (ex: "#124"), mas também o seu **primeiro nome** (ex: "João") logo abaixo do número, numa fonte menor e legível.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Rótulo do Botão (Button Label)**:
+  - O **Número do Beneficiário** continua a ser exibido em destaque na parte superior do botão.
+  - O **Primeiro Nome** do beneficiário deve ser exibido logo abaixo do número, centralizado, com estilo de texto menor (ex: classe Bootstrap `small` ou `text-muted`).
+- **Tratamento do Nome**:
+  - Deve ser exibido **apenas o primeiro nome** (a primeira palavra do campo `name` na base de dados). Exemplo: "Maria Eduarda Santos" deve ser exibido como "Maria".
+  - O texto do nome deve ser ajustado ou truncado se necessário, para garantir que não quebre o layout quadrado do botão tátil.
+
+### 2. Comportamento e Regras de Negócio
+- O sistema deve extrair de forma robusta o primeiro nome a partir do nome completo registado na tabela `beneficiaries`.
+- Se o campo do nome contiver apenas um nome, exibe esse nome normalmente.
+- Se o nome contiver espaços ou hífens, extrai a primeira palavra delimitada por espaços.
+
+### 3. Integração de Dados
+- Os dados do beneficiário (`name` e `number`) são os mesmos carregados a partir da tabela `beneficiaries` no servidor. Não são necessárias alterações no modelo de dados da base de dados SQLite.
@@ -0,0 +1,26 @@
+# US11 - Ajustes de Navegação (Menu Entregas e Gestão)
+
+**Como** Utilizador do RefoodOne
+**Quero** que o menu "Entregas" seja exibido diretamente na barra de navegação principal e que o menu "Gestão" (dropdown) seja visível apenas para Administradores (role `admin`)
+**Para** otimizar o acesso rápido dos voluntários e gestores de turno à funcionalidade de entregas, mantendo os painéis administrativos visíveis apenas para os administradores.
+
+## Descrição do Fluxo
+Ao fazer login na aplicação:
+- Um utilizador com o perfil **Administrador (Admin)** visualiza a opção **Gestão** (que contém os submenus **Beneficiários** e **Turnos**) e, ao lado desta, a opção **Entregas** exposta diretamente.
+- Um utilizador com o perfil **Gestor de Turno** ou **Voluntário** visualiza apenas a opção **Entregas** diretamente exposta no cabeçalho principal. O menu **Gestão** fica ocultado para estes utilizadores.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Menu Entregas**: Deve ser um link principal exposto diretamente no cabeçalho de navegação (navbar), posicionado ao lado do menu Gestão para administradores.
+- **Menu Gestão (Dropdown)**:
+  - Fica visível **apenas** para utilizadores com o perfil de administrador (`role === 'admin'`).
+  - Passa a conter no seu submenu dropdown apenas as opções **Beneficiários** e **Turnos**.
+- **Idioma**: Toda a barra de navegação deve continuar a utilizar termos em PT-PT.
+
+### 2. Comportamento e Regras de Negócio
+- Utilizadores com perfil `shift_manager` e `volunteer` não devem ter acesso visual ao menu Gestão.
+- A proteção de rotas no servidor (`hooks.server.ts`) deve continuar a garantir que apenas `admin` aceda a `/admin/beneficiarios`, e que apenas `admin` e `shift_manager` acedam a `/admin/turnos`.
+
+### 3. Integração de Dados
+- O cabeçalho de navegação (`+layout.svelte`) lê o perfil de utilizador (`data.user.role`) a partir dos dados carregados do servidor para aplicar as regras de visibilidade.
@@ -0,0 +1,28 @@
+# US12 - Apagar Registo de Entrega Diário
+
+**Como** Utilizador do RefoodOne (Administrador / Gestor de Turno / Voluntário)
+**Quero** poder apagar um registo de entrega efetuado hoje através de um botão na lista de entregas diárias
+**Para** corrigir eventuais enganos no registo e permitir que o botão do beneficiário fique novamente ativo para novo registo.
+
+## Descrição do Fluxo
+Ao aceder ao ecrã de entregas:
+1. O utilizador visualiza a lista "Entregas de Hoje" no fundo da página.
+2. Cada linha da tabela de entregas apresenta uma nova coluna com um botão para apagar (ex: ícone de lixo/remover).
+3. Ao clicar no botão de apagar, o registo de entrega é eliminado e o botão correspondente do beneficiário na grelha superior volta a ficar disponível (ativo/clicável) imediatamente.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Tabela de Entregas**: 
+  - Adição de uma nova coluna sem cabeçalho (ou cabeçalho "Ações") no final da tabela.
+  - Exibição de um botão de eliminação em cada linha (por exemplo, botão com ícone de caixote do lixo em tons vermelhos ou contornos suaves).
+- **Grelha de Beneficiários**:
+  - Após a eliminação com sucesso, o botão do beneficiário correspondente deixa de estar no estado desabilitado/entregue e regressa ao estado ativo original.
+
+### 2. Comportamento e Regras de Negócio
+- O botão de apagar elimina definitivamente o registo de entrega da base de dados correspondente àquele dia e beneficiário.
+- Deve ser usado um mecanismo reativo ou atualização de página (ex: `use:enhance`) para atualizar imediatamente a tabela de entregas e a grelha de botões de beneficiários sem necessidade de recarregar a página manualmente.
+
+### 3. Integração de Dados / Segurança
+- **Base de Dados**: O registo correspondente à entrega deve ser eliminado da tabela `entregas`.
+- **Permissões**: Qualquer perfil autenticado com acesso ao ecrã de entregas pode efetuar a eliminação para retificar erros de registo imediatos.
@@ -0,0 +1,42 @@
+# US13 - Gestão de Utilizadores
+
+**Como** Administrador do RefoodOne
+**Quero** poder visualizar e gerir as contas de utilizadores (voluntários, gestores de turno e administradores) do sistema
+**Para** controlar os perfis de acesso e atualizar as credenciais dos utilizadores de forma segura.
+
+## Descrição do Fluxo
+Ao aceder ao sistema como administrador:
+1. O utilizador encontra um novo submenu **Utilizadores** no menu dropdown principal **Gestão**.
+2. Ao selecionar **Utilizadores**, é direcionado para o ecrã de listagem de utilizadores.
+3. No ecrã de listagem, pode ver uma tabela contendo o **Nome de Utilizador** e o **Perfil (Role)** de cada conta registada. Cada linha tem uma opção/link para aceder ao detalhe do utilizador.
+4. No ecrã de detalhe de um utilizador, o administrador pode:
+   - Alterar o **Nome de Utilizador**.
+   - Alterar o **Perfil** (selecionando numa lista dropdown as opções: *Administrador*, *Gestor de Turno*, *Voluntário*).
+   - Definir uma nova password na secção correspondente, inserindo a nova password e confirmando a mesma num segundo campo (não sendo necessária a password antiga).
+5. O administrador clica em Guardar para persistir as alterações na base de dados.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Menu Gestão**: Adicionar a ligação para "Utilizadores" no menu dropdown do cabeçalho principal.
+- **Ecrã de Listagem**:
+  - Tabela com colunas: **Nome** (`username`) e **Perfil** (`role`).
+  - Botão ou ligação para editar o detalhe em cada linha de utilizador.
+- **Ecrã de Detalhe**:
+  - Campo de texto para o **Nome de Utilizador**.
+  - Dropdown com as roles suportadas em PT-PT:
+    - *Administrador* (`admin`)
+    - *Gestor de Turno* (`shift_manager`)
+    - *Voluntário* (`volunteer`)
+  - Secção "Alterar Password" contendo dois campos de texto/password: **Nova Password** e **Confirmar Nova Password**.
+  - Mensagens de erro/sucesso claras em português.
+
+### 2. Comportamento e Regras de Negócio
+- Apenas utilizadores com a role `admin` podem aceder a estes ecrãs (tanto a listagem como o detalhe).
+- Se a secção de password for preenchida, o sistema deve validar se as duas passwords coincidem e se cumprem requisitos mínimos de segurança (ex: tamanho mínimo).
+- Se a secção de password for deixada em branco, o utilizador é guardado mantendo a password antiga sem alterações.
+- O ecrã de detalhe também deve permitir criar um utilizador novo (ou ter um fluxo correspondente) com os mesmos campos.
+
+### 3. Integração de Dados / Segurança
+- **Segurança**: As novas passwords devem ser encriptadas de forma segura (ex: hashing) antes de guardar na tabela `users` da base de dados.
+- **Controlo de Acesso**: Bloqueio de acesso a nível de rotas no servidor (`hooks.server.ts` ou páginas locais) para utilizadores que não tenham perfil `admin`.
@@ -0,0 +1,32 @@
+# US14 - Homepage com Botões de Atalho (Tablet-Optimized)
+
+**Como** Utilizador do RefoodOne
+**Quero** ter uma página inicial simples com botões táteis de grande dimensão e ícones ilustrativos
+**Para** aceder de forma rápida e intuitiva às funcionalidades autorizadas a partir de um tablet.
+
+## Descrição do Fluxo
+Ao iniciar a aplicação e fazer login:
+1. O utilizador é direcionado para a Homepage (`/`).
+2. Dependendo do seu perfil de utilizador, são apresentados botões táteis grandes organizados numa grelha responsiva:
+   - **Voluntário** e **Gestor de Turno**: Visualizam apenas o botão **Entregas** (com ícone de cabaz/cesto de compras).
+   - **Administrador**: Visualiza três botões: **Entregas** (ícone de cabaz), **Utilizadores** (ícone de pessoas/contas) e **Beneficiários** (ícone de grupo/lista).
+3. Ao clicar num dos botões grandes, o utilizador é encaminhado para a respetiva secção do sistema.
+
+## Critérios de Aceitação
+
+### 1. Interface Gráfica (UI)
+- **Design para Tablet**:
+  - Grelha centrada no ecrã com botões de tamanho generoso (ex: cartões táteis com pelo menos 140x140px), facilmente clicáveis com um dedo.
+  - Efeitos visuais modernos ao passar o rato (hover) ou tocar no ecrã.
+- **Botões e Ícones**:
+  - **Entregas**: Rótulo "Entregas", com um ícone representativo de cabaz/cesto (SVG).
+  - **Beneficiários**: Rótulo "Beneficiários", com um ícone representativo de lista/pessoas (SVG).
+  - **Utilizadores**: Rótulo "Utilizadores", com um ícone representativo de utilizadores/chaves (SVG).
+- **Idioma**: Todos os rótulos e textos em PT-PT.
+
+### 2. Comportamento e Regras de Negócio
+- A visualização dos botões deve respeitar rigorosamente o perfil do utilizador autenticado (`data.user.role`).
+- Utilizadores sem o perfil `admin` (ex: `volunteer` e `shift_manager`) não devem ver os botões de administração (Beneficiários e Utilizadores) no ecrã inicial.
+
+### 3. Integração de Dados
+- A página lê a informação do utilizador a partir dos dados locais carregados (`data.user`) na rota raiz (`/`).
@@ -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.