DK Fashion - Documentação
Portal de documentação do DK Fashion, marketplace de moda desenvolvido para uma cliente real a partir de elicitação contínua de requisitos.
Sobre o projeto
O DK Fashion nasce da necessidade de levar para o digital uma loja de moda que já opera fisicamente. Em vez de substituir a operação existente, a plataforma integra os dois canais: o mesmo catálogo, o mesmo estoque e a mesma base de clientes atendem tanto a venda presencial quanto a venda on-line.
O sistema é composto por uma loja virtual voltada ao cliente final e por um painel administrativo usado pela equipe da loja. Entre as capacidades previstas no backlog e nos requisitos não funcionais estão:
- Catálogo e vitrine — cadastro de produtos com variações de cor e tamanho, imagens, busca com filtros e página de detalhes;
- Compra on-line — carrinho, múltiplas formas de pagamento (Pix, crédito e débito), cálculo de frete, rastreamento e retirada na loja física;
- Operação da loja — registro de vendas presenciais, sincronização de estoque entre os canais, histórico auditável de alterações e níveis de acesso por perfil (cliente, caixa, vendedor, gerente e administrador);
- Relacionamento e marketing — cadastro de clientes, cupons de desconto, cupons de parceiros e exportação da base para campanhas de mídia paga;
- Gestão de desempenho — vínculo de vendedor por transação, cálculo de comissão, metas mensais, ranking e acompanhamento de progresso;
- Pós-venda e fiscal — avaliações de produtos com moderação, trocas e integração com emissão de NF-e.
Objetivo desta documentação
Esta documentação organiza, em um único lugar, as fontes de conhecimento que o projeto acumulou — decisões de produto, decisões técnicas e o registro do que vem sendo construído:
| Fonte de conhecimento | Onde está |
|---|---|
| Decisões de requisitos elicitadas com a cliente: histórias de usuário e requisitos não funcionais | Backlog e Requisitos Não Funcionais |
| Registro das conversas que originaram essas decisões | Atas de reunião |
| Detalhamento da arquitetura do banco de dados | Modelo Físico do Banco de Dados |
| Detalhamento da prototipação e dos fluxos de interface | Protótipo |
| Documentação das sprints e do desenvolvimento em andamento | Sprints |
| Guia de contribuição para o projeto open source | Guia de Contribuição |
| Fluxo de branches, revisão e release adotado | Gitflow do Projeto |
Controle de qualidade
Antes de abrir um Pull Request, rode os checks que também são executados no CI:
make quality
| Comando | O que faz |
|---|---|
make lint-md |
Valida estilo e consistência do Markdown com o markdownlint-cli2 |
make lint-md-fix |
Corrige automaticamente o que for corrigível |
make check-links |
Roda mkdocs build --strict e varre o HTML gerado com o LinkChecker |
make check-links-extern |
Igual ao anterior, incluindo links externos |
Estrutura do repositório
.
|-- docs/
| |-- index.md
| |-- backlog.md
| |-- non_functional_requirements.md
| |-- physical_data_model.md
| |-- prototipo.md
| |-- contributing_guidelines.md
| |-- gitflow.md
| |-- sprints.md
| |-- atas_reuniao/
| |-- sprints/
| `-- user_history/
|-- slides/
| `-- template.md
|-- qa-analytics/
| |-- dashboard.py
| `-- requirements.txt
|-- scripts/
| |-- build-slides.sh
| `-- check-links.sh
|-- mkdocs.yml
|-- Dockerfile
|-- compose.yaml
|-- requirements.txt
|-- requirements-dev.txt
|-- .markdownlint-cli2.jsonc
|-- .linkcheckerrc
|-- Makefile
`-- README.md
Equipe TPPE (26.1)
Equipe GCES (26.2) - Em atividade
Como executar
O fluxo oficial do projeto é via Docker: não é preciso instalar Python ou MkDocs na máquina, nem criar ambiente virtual.
- Suba a documentação:
make serve
# ou
make serve-background # sobe como Daemon
- Acesse a documentação:
http://localhost:8000
- Para encerrar:
make stop
Como o projeto é montado como volume no container, alterações em docs/ e
mkdocs.yml são refletidas no navegador com hot reload. Se mudar o
requirements.txt, rode make serve novamente para reconstruir a imagem.
Tecnologias utilizadas
As tecnologias abaixo são as do projeto DK Fashion como um todo, e não apenas as deste repositório de documentação.
Front-end
| Tecnologia | Papel |
|---|---|
| React + TypeScript | Interface da loja e do painel administrativo (SPA) |
| Vite | Build e servidor de desenvolvimento |
| TailwindCSS | Estilização e design system da interface |
| Figma | Prototipação de alta fidelidade que guia a implementação |
Back-end
| Tecnologia | Papel |
|---|---|
| NestJS + TypeScript | API REST modular, organizada por domínio |
| TypeORM | Mapeamento objeto-relacional e migrações de esquema |
| PostgreSQL | Banco de dados relacional |
| JWT | Autenticação e controle de acesso por perfil |
| Jest | Testes automatizados |
Documentação
| Tecnologia | Papel |
|---|---|
| MkDocs + Material for MkDocs | Geração e tema do portal de documentação |
| markdownlint-cli2 | Padronização do Markdown |
| LinkChecker | Verificação de links quebrados |
| Marp | Slides das apresentações de sprint |
Infraestrutura e qualidade
| Tecnologia | Papel |
|---|---|
| Docker e Docker Compose | Conteinerização dos ambientes de desenvolvimento |
| GitHub Actions | Integração e entrega contínuas |
| SonarCloud | Análise estática e métricas de qualidade do código |
| Render e Vercel | Hospedagem da API e do front-end (ver orçamento) |
Histórico de Versionamento
| Versão | Autor | Resumo | Data |
|---|---|---|---|
1.0 |
Bruno Bragança | Criação da página inicial da documentação | 26/03/2026 |
1.1 |
Bruno Bragança | Atualização da página inicial com a equipe do projeto | 30/03/2026 |
1.2 |
Bruno Bragança | Atualização das instruções de execução para o fluxo com Docker | 06/04/2026 |
1.3 |
Bruno Bragança | Inclusão da seção de controle de qualidade da documentação | 01/09/2026 |
1.4 |
Eduardo Matheus | Adição da equipe GCES (26.2) e do atalho para servir a documentação em segundo plano | 04/09/2026 |
1.5 |
Bruno Bragança | Descrição do projeto, objetivo da documentação e tecnologias separadas por front-end, back-end e documentação | 14/09/2026 |