UI Prototype

Um protótipo moderno de aplicação web construído com React, TypeScript e Material-UI, com autenticação, internacionalização e integração com Figma.

GitHub
1
Experimente este MCPPatrocinado

Documentação

UI Prototype

📖 Visão Geral

Este projeto é uma aplicação web que utiliza React + TypeScript + Material-UI (MUI) com foco em um visual moderno. Inclui funcionalidades como autenticação, suporte a múltiplos idiomas, ambiente de testes, API mock com MSW (Mock Service Worker) e integração com o servidor MCP do Figma.

✨ Principais Características

  • 🔐 Sistema de Autenticação: Autenticação e gerenciamento de sessão
  • 🌍 Suporte a Múltiplos Idiomas: Suporte a japonês e inglês (react-i18next)
  • 🧪 Testes Abrangentes: Vitest + React Testing Library + Playwright E2E
  • 🎭 API Mock: Mock de API em desenvolvimento com MSW
  • 🎨 Integração com Figma: Obtenção de assets de design via servidor MCP
  • 📱 Design Responsivo: Suporte a mobile e desktop (não tão completo)

🛠 Stack Tecnológico

  • Frontend: React 19, TypeScript
  • UI Framework: Material-UI (MUI)
  • Build Tool: Vite
  • Gerenciamento de Estado: TanStack Query (React Query)
  • Roteamento: React Router
  • Testes: Vitest, React Testing Library, Playwright
  • Mocking: MSW (Mock Service Worker)
  • Internacionalização: react-i18next
  • Geração de Código: Orval (OpenAPI)
  • Gerenciador de Pacotes: pnpm

🚀 Início Rápido

Pré-requisitos

  • Node.js (v22) gerenciado automaticamente pelo projeto
  • pnpm (v10.12.4) gerenciado automaticamente pelo projeto

Gerenciamento de Versão:

  • Node.js: .npmrc baixa e usa automaticamente a versão v22.17.0
  • pnpm: packageManager recomenda a versão v10.12.4

Os desenvolvedores não precisam gerenciar versões manualmente.

Instalação e Execução

# 依存関係のインストール
pnpm install

# E2Eテスト用ブラウザのインストール（初回のみ）
pnpm test:e2e:install

# 環境変数の設定（オプション）
cp .env.sample .env
# .envファイルを編集してAPI URLなどを設定

# OpenAPIスキーマからコードとモックを生成（初回またはスキーマ更新時）
pnpm gen:api

# 開発サーバーの起動
pnpm dev

A aplicação inicia em http://localhost:5173.

📁 Estrutura do Projeto

src/
├── adapters/          # 外部サービスとの接続層
│   ├── axios.ts       # HTTP クライアント設定
│   ├── generated/     # OpenAPI から生成されたコード
│   ├── mocks/         # MSW モック定義
│   └── repositories/  # データアクセス層
├── app/               # アプリケーション設定
│   ├── providers/     # Context Providers
│   ├── router/        # ルーティング設定
│   └── types/         # アプリケーション型定義
├── domain/            # ビジネスロジック層
│   ├── constants/     # 定数定義
│   ├── errors/        # エラー型定義
│   ├── models/        # ドメインモデル
│   └── utils/         # ユーティリティ関数
├── i18n/              # 国際化設定
│   ├── config.ts      # i18n 設定
│   ├── hooks/         # 翻訳フック
│   └── locales/       # 言語ファイル
└── presentations/     # プレゼンテーション層
    ├── components/    # 共通コンポーネント
    ├── hooks/         # カスタムフック
    ├── layouts/       # レイアウトコンポーネント
    └── pages/         # ページコンポーネント

Características da Arquitetura

  • Clean Architecture: Separação em camadas baseada nos princípios de Domain-Driven Design
  • Repository Pattern: Abstração do acesso a dados
  • Provider Pattern: Injeção de dependências e gerenciamento de contexto
  • Custom Hooks: Reutilização da lógica de negócio

🔧 Funcionalidades Principais

Sistema de Autenticação

  • Autenticação baseada em JWT
  • Gerenciamento de sessão e renovação automática
  • Funcionalidades de login/logout
  • Roteamento baseado no estado de autenticação

Suporte a Múltiplos Idiomas

  • Suporte a japonês e inglês
  • Alternância dinâmica de idioma com react-i18next
  • Chaves de tradução com segurança de tipos

Comunicação com API

  • Cliente HTTP baseado em Axios
  • Geração automática a partir do esquema OpenAPI
  • Tratamento de erros e funcionalidade de retry

🧪 Testes

Execução de Testes

# 単体テスト（Vitest）
pnpm test                # 全テスト実行
pnpm test:watch          # ウォッチモード
pnpm test:coverage       # カバレッジ付き実行
pnpm test:related src/path/to/changed-file.tsx  # 関連テストのみ実行

# E2Eテスト（Playwright）
pnpm test:e2e:install    # ブラウザインストール（初回のみ）
pnpm test:e2e            # 全E2Eテスト実行
pnpm test:e2e:ui         # インタラクティブモード
pnpm test:e2e:debug      # デバッグモード

Detalhes dos Testes E2E: Consulte playwright/README.md.

Na primeira execução: Instale os navegadores do Playwright (Chromium, Firefox, WebKit) com pnpm test:e2e:install.

Estratégia de Testes

  • Testes Unitários: Testes de componentes, hooks e funções utilitárias
  • Testes de Integração: Testes de interação do usuário no nível de página
  • Testes E2E: Testes de ponta a ponta em navegadores reais com Playwright
  • Execução de Testes Relacionados: Execução eficiente de testes com o comando test:related
    • Detecta e executa automaticamente apenas os arquivos de teste relacionados aos arquivos alterados
    • Proporciona um ciclo de feedback rápido em ambientes CI/CD
    • Reduz o tempo de teste com execução paralela (shard)
  • Estratégia de Mock:
    • Mock de respostas de API com MSW
    • Mock parcial no nível de Repository
    • Padronização com utilitários de teste

Estrutura de Testes

  • src/__fixtures__/: Helpers e dados mock para testes
  • src/__tests__/: Testes no nível de aplicação
  • __tests__/ em cada diretório: Testes unitários de componentes e hooks

🔌 Integração MCP (Model Context Protocol)

Este projeto pode ser integrado a ferramentas de IA usando servidores MCP para otimizar o desenvolvimento.

Arquivos de Configuração

O projeto usa dois tipos de arquivos de configuração MCP:

  • .mcp.json: Configuração MCP por projeto do Claude Code
  • .vscode/mcp.json: Configuração MCP para VSCode / GitHub Copilot

Ambos os arquivos configuram os mesmos servidores MCP, mas são usados por ferramentas diferentes.

Servidores MCP Disponíveis

1. Servidor MCP do Figma

Permite obter assets diretamente de arquivos de design do Figma.

Configuração:

Adicione seu Personal Access Token do Figma à configuração:

{
  "servers": {
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

Como usar:

Implemente componentes a partir de designs do Figma com ferramentas de IA:

Figma URL: https://www.figma.com/file/YOUR_FILE_KEY/...

このFigmaデザインを参考に、LoginButtonコンポーネントを実装してください。
- styled.tsx にスタイル定義をまとめる
- Material-UIベースで実装
- レスポンシブ対応
- Figmaの色・サイズ・余白を反映

Funcionalidades disponíveis:

  • Obter informações de layout de arquivos do Figma
  • Baixar imagens e ícones do Figma

2. Servidor MCP do Playwright

Auxilia na geração automática de testes E2E e operações de navegador.

Configuração:

Já está configurado. Você pode personalizar as configurações em .vscode/playwright-config.json.

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "pnpm",
      "args": [
        "dlx",
        "@playwright/mcp@latest",
        "--config",
        ".vscode/playwright-config.json"
      ]
    }
  }
}

Como usar:

Gere e execute testes Playwright com ferramentas de IA:

ログインページのE2Eテストを作成してください。
- メールとパスワードを入力
- ログインボタンをクリック
- ダッシュボードにリダイレクトされることを確認

Funcionalidades disponíveis:

  • Geração automática de código de teste Playwright
  • Auxílio na criação de scripts de operação de navegador
  • Suporte à implementação do padrão Page Object Model

🔧 Detalhes das Ferramentas de Desenvolvimento

Configuração do MSW (Mock Service Worker)

Configuração para usar mock de API em desenvolvimento:

# MSWの初期化（公開ディレクトリにService Workerファイルを生成）
pnpm msw:init

Este comando gera public/mockServiceWorker.js, habilitando o mock de API no navegador.

Scripts Disponíveis

pnpm dev           # 開発サーバー起動
pnpm build         # プロダクションビルド
pnpm type-check    # 型チェック
pnpm lint          # ESLint実行
pnpm format:check  # Prettierによるフォーマットチェック（チェックのみ）
pnpm format:fix    # Prettierによるコードフォーマット（コードを自動整形）
pnpm preview       # ビルド結果をプレビュー
pnpm test          # テスト実行
pnpm test:run      # watch モードなしで実行
pnpm test:coverage # カバレッジ付きテスト
pnpm test:related  # 関連テストのみ実行（指定ファイルに関連するテストを検出）
pnpm gen:api       # OpenAPIからコードとモックを生成
pnpm msw:init      # MSW Service Worker初期化

Geração de Código (Orval)

Geração automática do cliente de API e mocks MSW a partir do esquema OpenAPI:

# OpenAPI スキーマから型とAPIクライアント、MSWモックを生成
pnpm gen:api

O Orval gera automaticamente:

  • Cliente de API: Cliente de API com segurança de tipos em src/adapters/generated/
  • Definições de tipos TypeScript: Definições de tipos baseadas no esquema OpenAPI
  • Mocks MSW: Handlers de mock em src/adapters/mocks/handlers/

Arquivo de configuração: schema/orval.config.ts

Configuração de Variáveis de Ambiente

O projeto permite configurar URLs de API e outras opções usando variáveis de ambiente:

# .env.sampleをコピーして.envファイルを作成
cp .env.sample .env

Variáveis de ambiente disponíveis:

  • VITE_API_BASE_URL: URL base da API (padrão: http://localhost:3000/api)

Exemplos de configuração por ambiente:

# 開発環境
VITE_API_BASE_URL=http://localhost:3000/api

# 本番環境
VITE_API_BASE_URL=https://api.your-domain.com/api

# ステージング環境
VITE_API_BASE_URL=https://staging-api.your-domain.com/api

As variáveis de ambiente são aplicadas automaticamente tanto ao baseURL do Axios quanto aos handlers de mock do MSW.

Configuração do Ambiente de Desenvolvimento

  • ESLint: Manutenção da qualidade do código
  • TypeScript: Garantia de segurança de tipos
  • Vite: Experiência de desenvolvimento rápida
  • pnpm: Gerenciamento eficiente de pacotes