Feature/readme

README.md

@@ -26,39 +26,49 @@ de usuário:
 
 ## Organização do repositório
 
-O repositório está dividido em duas pastas, correspondentes às duas atividades
-da disciplina realizadas até o momento:
-
-- **`A1/`** — arquivos em LaTeX e PDF que definem  o processo de
-  desenvolvimento do projeto (Atividade 1).
-- **`A2/`** — todo o projeto descrito neste README (Atividade 2): código-fonte,
-  testes e o `main.py` da aplicação.
+O repositório reúne o código da aplicação (na raiz) e a documentação das
+atividades da disciplina (em `docs/`):
+
+- **Raiz (`main.py`, `src/`, `tests/`)** — o projeto descrito neste README
+  (Atividade 2): código-fonte, testes e o ponto de entrada da aplicação.
+- **`docs/A1_report/`** — relatório da Atividade 1 (LaTeX e PDF) com a definição
+  do processo de desenvolvimento, incluindo diagramas (casos de uso, domínio,
+  processo) e protótipos de telas.
+- **`docs/A3_report/`** — relatório da Atividade 3 (LaTeX): elicitação e análise
+  de requisitos, épicos, histórias de usuário e backlog priorizado. **Em
+  andamento.**
+- **`.github/workflows/ci.yml`** — pipeline de integração contínua (ver
+  [Integração contínua](#integração-contínua)).
 
 As seções abaixo (estrutura, como rodar, testes) se referem ao conteúdo da
 pasta `A2/`.
 
 ## Estrutura do projeto
 
-> ⚠️ **Status: prévia inicial.** Esta versão cobre a lógica central do projeto e uma interface de linha de comando (CLI) mínima para navegar por ela..
+> ⚠️ **Status: prévia inicial.** Esta versão cobre a lógica central dos três
+> contextos e uma interface de linha de comando (CLI) para navegar por ela.
+> Veja [Status do projeto e próximos passos](#status-do-projeto-e-próximos-passos).
 
 ```
 .
-├── A1/                         # Atividade 1: documentação do processo (LaTeX/PDF)
-└── A2/                         # Atividade 2: implementação do projeto
-    ├── main.py                    # ponto de entrada da aplicação
-    ├── requirements.txt           # dependências de teste/lint
-    ├── src/
-    │   ├── caco.py                # motor da Assembleia do CACo
-    │   ├── australia.py           # motor da Eleição Austrália (voto transferível)
-    │   ├── botc.py                # motor do Blood on the Clocktower
-    │   ├── interfaces.py          # interface comum aos motores de votação
-    │   ├── autenticacao/          # usuários, perfis (escopos) e serviço de login
-    │   └── cli/                   # loop principal e telas do terminal
-    │       ├── app.py
-    │       ├── sessao.py
-    │       ├── cli_utils.py
-    │       └── telas/             # uma tela por fluxo (login, cadastro, cada contexto, etc.)
-    └── tests/                     # testes automatizados (pytest) de domínio e de interface
+├── main.py                        # ponto de entrada da aplicação
+├── requirements.txt               # dependências de teste/lint
+├── src/
+│   ├── caco.py                    # motor da Assembleia do CACo
+│   ├── australia.py               # motor da Eleição Austrália (voto transferível)
+│   ├── botc.py                    # motor do Blood on the Clocktower
+│   ├── interfaces.py              # interface comum aos motores de votação
+│   ├── autenticacao/              # usuários, perfis (escopos) e serviço de login
+│   └── cli/                       # loop principal e telas do terminal
+│       ├── app.py                 
+│       ├── sessao.py              
+│       ├── cli_utils.py
+│       └── telas/                 # uma tela por fluxo (login, cadastro, cada contexto, etc.)
+├── tests/                         # testes automatizados (pytest) de domínio, autenticação e interface
+├── docs/
+│   ├── A1_report/                 # Atividade 1: processo de desenvolvimento
+│   └── A3_report/                 # Atividade 3: requisitos
+└── .github/workflows/ci.yml       # CI: build, lint (ruff) e testes (pytest + cobertura)
 ```
 
 ## Requisitos
@@ -68,15 +78,12 @@ pasta `A2/`.
 
 ## Como rodar
 
-A partir da pasta `A2/` (raiz do código do projeto):
+A partir da raiz do repositório:
 
 ```bash
-cd A2
 python3 main.py
 ```
 
-> O programa precisa ser executado a partir da raiz de `A2/`, pois os
-> módulos são importados como `src...`.
 
 Ao iniciar, é possível **criar uma conta nova** ou **entrar** com um dos
 usuários de demonstração já cadastrados em `main.py`:
@@ -92,42 +99,41 @@ usuários de demonstração já cadastrados em `main.py`:
 
 ## Como rodar os testes
 
-Também a partir da pasta `A2/`:
+Também a partir da raiz do repositório:
+
+
+## Como rodar os testes
+
+Também a partir da raiz do repositório:
 
 ```bash
 pip install -r requirements.txt
 pytest
 ```
 
+Para ver a cobertura de testes (como na CI):
+
+```bash
+pytest --cov=src --cov-report=term
+```
 
 Para checar o estilo do código:
 
 ```bash
-ruff check .
+ruff check src/ tests/
 ```
 
 ## Status do projeto e próximos passos
 
-Esta entrega tem como foco validar a lógica de negócio de cada sistema eleitoral e uma navegação básica entre as telas. Alguns dos próximos passos já mapeados para as próximas entregas da disciplina, organizados por área, são:
-
-#### Autenticação
-- Salvar usuário entre as sessões
-
-#### Eleição da Austrália
-- Validação de duas camadas para candidatos com o mesmo nome
-- Impedir que o mesmo usuário vote duas vezes
-
-#### Assembleia do CACo
-- Tempo de votação
-- Conferir se o votante está na lista de estudantes
+Esta entrega tem como elicitar requisitos para guiar o desenvolvimento do projeto.
 
-#### Blood on the Clocktower
-- Implementar toda a mecânica do jogo de girar "ao redor do relógio",
-  conferindo jogador por jogador
+Os próximos passos estão organizados no quadro do GitHub Projects:
 
-#### Interface
-- Permitir mais de uma votação por sessão (hoje, para uma nova votação do CACo, por exemplo, após uma votação ser encerrada é necessário iniciar uma nova sessão)
-- Desenvolver uma interface propriamente dita, não em terminal
+**[Projeto MC656 no GitHub Projects](https://github.com/users/GiizAzul/projects/1)**
 
-Essas melhorias, entre outras, serão trabalhadas nas próximas entregas do
-projeto.
+- **Issues:** as issues com a label `Atividade3` vieram do levantamento de
+  requisitos da Atividade 3 (épicos e histórias de usuário com critérios de
+  aceitação) e formam o backlog priorizado do projeto.
+- **Documentação:** o processo de elicitação, a análise, os requisitos, os
+  épicos, as histórias e a priorização estão explicados em detalhe em
+  [`docs/A3_report/`](docs/A3_report).