pos-system/apps/client-example

🚀 Enterprise Microservice Client

Ứng dụng frontend NextJS cho hệ thống Microservice Enterprise với Advanced RBAC.

🎯 Tính năng

• ✅ Authentication & Authorization - Đăng nhập/đăng ký với JWT
• ✅ Advanced RBAC - Role-based access control với permissions chi tiết
• ✅ Modern UI/UX - Thiết kế responsive với Tailwind CSS
• ✅ Type Safety - TypeScript với type definitions đầy đủ
• ✅ Real-time Updates - Context-based state management
• ✅ Error Handling - Error boundaries và user-friendly messages

📋 Yêu cầu

• Node.js >= 18.0.0
• npm hoặc yarn
• Auth Service đang chạy trên port 7001

🚀 Cài đặt và chạy

1. Cài đặt dependencies

npm install
# hoặc
yarn install

2. Cấu hình environment

Tạo file .env.local:

# Auth Service URL
NEXT_PUBLIC_AUTH_SERVICE_URL=http://localhost:7001

# Client Configuration  
NEXT_PUBLIC_CLIENT_URL=http://localhost:3001

# API Configuration
NEXT_PUBLIC_API_VERSION=v1

# Development Settings
NODE_ENV=development

3. Chạy ứng dụng

# Development mode
npm run dev
# hoặc
yarn dev

# Production build
npm run build && npm run start
# hoặc  
yarn build && yarn start

Ứng dụng sẽ chạy tại: http://localhost:3001

🏗️ Cấu trúc thư mục

src/
├── app/                    # App Router pages
│   ├── auth/              # Authentication pages
│   │   ├── login/         # Login page
│   │   └── register/      # Register page
│   ├── dashboard/         # Protected dashboard
│   ├── layout.tsx         # Root layout với AuthProvider
│   └── page.tsx           # Home page
├── components/            
│   ├── auth/              # Auth components
│   │   ├── LoginForm.tsx  # Login form
│   │   └── RegisterForm.tsx # Register form
│   └── ui/                # Reusable UI components
├── contexts/              
│   └── AuthContext.tsx    # Authentication context
├── lib/                   
│   └── auth.service.ts    # Auth API service
├── types/                 
│   └── auth.ts            # Auth type definitions
└── styles/
    └── globals.css        # Global styles

🔐 Authentication Flow

1. Đăng ký (Register)

• Form validation (email, password strength, terms acceptance)
• Gửi request đến Auth Service /api/auth/register
• Auto login sau khi đăng ký thành công
• Redirect đến dashboard

2. Đăng nhập (Login)

• Email/password validation
• JWT token storage (localStorage)
• Refresh token mechanism
• Remember me option

3. Authorization

• Role-based access control
• Permission checking hooks
• Protected routes với middleware
• Auto redirect cho unauthorized access

4. Session Management

• Auto token refresh
• Persistent login state
• Logout functionality
• Token expiration handling

🎨 UI Components

Auth Components

• LoginForm - Form đăng nhập với validation
• RegisterForm - Form đăng ký với password strength
• AuthProvider - Context provider cho authentication state

UI Components

• Button - Component button với variants
• Card - Container component với styling
• Toast - Notification system với react-hot-toast

🔧 Auth Service Integration

API Endpoints

POST /api/auth/login      # Đăng nhập
POST /api/auth/register   # Đăng ký  
POST /api/auth/logout     # Đăng xuất
POST /api/auth/refresh    # Refresh token
GET  /api/auth/me         # Current user info
PUT  /api/auth/profile    # Update profile

Error Handling

• Network errors với retry mechanism
• Validation errors với field-level messages
• Auth errors với appropriate redirects
• User-friendly error messages trong tiếng Việt

📱 Responsive Design

• Mobile First - Thiết kế ưu tiên mobile
• Breakpoints - sm, md, lg, xl responsive breakpoints
• Touch Friendly - UI elements tối ưu cho touch
• Performance - Lazy loading và code splitting

🛡️ Security Features

• CSRF Protection - Cross-site request forgery protection
• XSS Prevention - Content Security Policy
• Secure Storage - Token storage với security best practices
• Input Validation - Client-side validation cho security
• Rate Limiting - Client-side rate limiting

🧪 Development

Commands

npm run dev       # Development server
npm run build     # Production build  
npm run start     # Production server
npm run lint      # ESLint checking
npm run type-check # TypeScript checking

Development Notes

• Hot reload enabled cho development
• TypeScript strict mode
• ESLint với Next.js recommended rules
• Prettier cho code formatting

🔗 Integration với Services

Auth Service (Port 7001)

• Authentication endpoints
• User management
• RBAC permissions
• Session handling

Future Services

• User Service (Port 7002) - User profiles & management
• Order Service (Port 7003) - Order processing
• API Gateway - Service orchestration

📖 Usage Examples

Protected Component

import { withAuth } from '@/contexts/AuthContext';

function ProtectedComponent() {
  return <div>Protected content</div>;
}

export default withAuth(ProtectedComponent);

Permission Checking

import { usePermissions } from '@/contexts/AuthContext';

function AdminPanel() {
  const { hasPermission, hasRole } = usePermissions();
  
  if (!hasRole('ADMIN')) {
    return <div>Access denied</div>;
  }
  
  return <div>Admin content</div>;
}

Auth State

import { useAuth } from '@/contexts/AuthContext';

function UserProfile() {
  const { user, logout, loading } = useAuth();
  
  if (loading) return <div>Loading...</div>;
  if (!user) return <div>Not authenticated</div>;
  
  return (
    <div>
      <h1>Welcome {user.firstName}!</h1>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

🚀 Deployment

Environment Variables

NEXT_PUBLIC_AUTH_SERVICE_URL=https://auth.yourdomain.com
NEXT_PUBLIC_CLIENT_URL=https://app.yourdomain.com  
NODE_ENV=production

Build & Deploy

npm run build
npm run start

📞 Support

• Documentation: /docs trong project root
• API Reference: Auth Service documentation
• Issues: GitHub issues cho bug reports
• Enterprise Support: Liên hệ team development

---

🎉 Happy Coding!

Hệ thống Enterprise Microservice với Advanced RBAC sẵn sàng phục vụ 10+ triệu users! 🚀