@finema/finework-layer 0.2.50 → 0.2.51

package/ARCHITECTURE.md

@@ -0,0 +1,592 @@
+# Architecture Documentation
+
+## 🏛️ System Architecture
+
+### Overview
+
+`@finema/finework-layer` follows a **layered architecture** pattern, serving as a middle layer between the core UI library and application-specific implementations.
+
+```
+┌─────────────────────────────────────────┐
+│     Application Layer                   │
+│  (Consuming Nuxt Projects)              │
+└─────────────────┬───────────────────────┘
+                  │ extends
+┌─────────────────▼───────────────────────┐
+│   @finema/finework-layer                │
+│  • Components                           │
+│  • Composables                          │
+│  • Layouts                              │
+│  • Middleware                           │
+│  • Constants                            │
+└─────────────────┬───────────────────────┘
+                  │ extends
+┌─────────────────▼───────────────────────┐
+│      @finema/core                       │
+│  • Base Components                      │
+│  • Data Loaders                         │
+│  • Form Utilities                       │
+│  • Core Composables                     │
+└─────────────────┬───────────────────────┘
+                  │ uses
+┌─────────────────▼───────────────────────┐
+│       @nuxt/ui                          │
+│  • UI Components                        │
+│  • Design System                        │
+│  • Theming                              │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 📦 Module Structure
+
+### 1. Components Layer
+
+**Purpose:** Reusable UI components specific to Finework applications
+
+```
+app/components/
+├── Button/
+│   ├── ActionIcon.vue      # Icon-only action buttons
+│   └── Back.vue            # Back navigation button
+├── Layout/
+│   ├── Admin/
+│   │   ├── index.vue       # Main admin layout
+│   │   └── Sidebar.vue     # Admin sidebar navigation
+│   ├── User/
+│   │   └── index.vue       # User-facing layout
+│   └── Apps.vue            # App switcher popover
+├── InfoItemList.vue        # Key-value display component
+└── StatusBox.vue           # Loading/error/empty states
+```
+
+**Design Principles:**
+- **Composition over Inheritance:** Components compose smaller components
+- **Single Responsibility:** Each component has one clear purpose
+- **Type Safety:** All props and emits are typed
+- **Accessibility:** ARIA labels and keyboard navigation
+
+### 2. Composables Layer
+
+**Purpose:** Reusable business logic and state management
+
+```
+app/composables/
+├── useAuth.ts              # Authentication & authorization
+└── useRequestOptions.ts    # HTTP request configuration
+```
+
+**Key Patterns:**
+- **Singleton Stores:** Using Pinia for shared state (e.g., `auth.me`)
+- **Computed Properties:** Reactive derived state
+- **Side Effects:** Watchers for state synchronization
+
+### 3. Middleware Layer
+
+**Purpose:** Route-level guards and logic
+
+```
+app/middleware/
+├── auth.ts                 # Authentication guard
+├── permissions.ts          # Permission-based access
+├── guest.ts                # Guest-only routes
+└── common.ts               # Common pre-route logic
+```
+
+**Execution Order:**
+1. `common.ts` - Always runs first
+2. `auth.ts` - Checks authentication
+3. `permissions.ts` - Validates permissions
+4. `guest.ts` - Redirects authenticated users
+
+### 4. Constants Layer
+
+**Purpose:** Centralized configuration and constants
+
+```
+app/constants/
+└── routes.ts               # Route definitions
+```
+
+**Benefits:**
+- Type-safe route references
+- Single source of truth
+- Easy refactoring
+- Auto-completion support
+
+---
+
+## 🔄 Data Flow Architecture
+
+### Authentication Flow
+
+```
+┌──────────────┐
+│   Browser    │
+└──────┬───────┘
+       │ 1. Navigate to protected route
+       ▼
+┌──────────────────────┐
+│  Middleware Chain    │
+│  ├─ common.ts        │
+│  ├─ auth.ts          │
+│  └─ permissions.ts   │
+└──────┬───────────────┘
+       │ 2. Check token cookie
+       ▼
+┌──────────────────────┐
+│   useAuth()          │
+│  ├─ token            │
+│  ├─ me (store)       │
+│  └─ fetchMe()        │
+└──────┬───────────────┘
+       │ 3. Fetch user if needed
+       ▼
+┌──────────────────────┐
+│   API Request        │
+│  GET /me             │
+│  Authorization: ...  │
+└──────┬───────────────┘
+       │ 4. Update store
+       ▼
+┌──────────────────────┐
+│   Pinia Store        │
+│  auth.me.value       │
+└──────┬───────────────┘
+       │ 5. Render page
+       ▼
+┌──────────────────────┐
+│   Page Component     │
+└──────────────────────┘
+```
+
+### Data Loading Flow
+
+```
+┌──────────────┐
+│  Component   │
+│  onMounted() │
+└──────┬───────┘
+       │ 1. Call loader.run()
+       ▼
+┌──────────────────────┐
+│  useObjectLoader     │
+│  (from @finema/core) │
+└──────┬───────────────┘
+       │ 2. Make HTTP request
+       ▼
+┌──────────────────────┐
+│  useRequestOptions   │
+│  ├─ auth()           │
+│  ├─ base()           │
+│  └─ file()           │
+└──────┬───────────────┘
+       │ 3. Add headers/config
+       ▼
+┌──────────────────────┐
+│   Axios Request      │
+└──────┬───────────────┘
+       │ 4. Response
+       ▼
+┌──────────────────────┐
+│  Loader State        │
+│  ├─ status           │
+│  │   ├─ isLoading    │
+│  │   ├─ isSuccess    │
+│  │   └─ isError      │
+│  └─ data             │
+└──────┬───────────────┘
+       │ 5. Reactive update
+       ▼
+┌──────────────────────┐
+│   StatusBox          │
+│  Shows appropriate   │
+│  state               │
+└──────────────────────┘
+```
+
+---
+
+## 🎨 Component Architecture
+
+### StatusBox Pattern
+
+**Problem:** Every data-loading component needs to handle:
+- Loading state
+- Error state
+- Empty state
+- Success state
+
+**Solution:** `StatusBox` component abstracts this logic
+
+```vue
+<StatusBox :status="loader.status.value" :data="loader.data.value">
+  <template #default="{ data }">
+    <!-- Only renders when data is successfully loaded -->
+  </template>
+</StatusBox>
+```
+
+**Benefits:**
+- Consistent UX across all pages
+- Reduced boilerplate
+- Centralized error handling
+- Easy to update globally
+
+### Layout Pattern
+
+**Problem:** Different user roles need different layouts
+
+**Solution:** Composable layout components
+
+```
+LayoutAdmin
+├─ Sidebar (collapsible)
+├─ Header (user menu, apps)
+└─ Main content area
+
+LayoutUser
+├─ Top navbar
+├─ Breadcrumbs
+└─ Main content area
+```
+
+**Features:**
+- Responsive design
+- Mobile-friendly
+- Consistent navigation
+- Role-based menus
+
+---
+
+## 🔐 Security Architecture
+
+### Authentication Layers
+
+1. **Cookie-based Token Storage**
+   - HttpOnly cookie (set by backend)
+   - Secure flag in production
+   - SameSite protection
+
+2. **Middleware Guards**
+   - Route-level protection
+   - Automatic redirects
+   - Token validation
+
+3. **Permission System**
+   - Module-based permissions
+   - Role hierarchy (USER < ADMIN < SUPER)
+   - Fine-grained access control
+
+### Permission Matrix
+
+```typescript
+interface IUserAccessLevel {
+  pmo: Permission        // PMO module access
+  clockin: Permission    // Clock-in module access
+  timesheet: Permission  // Timesheet module access
+  setting: Permission    // Settings module access
+}
+
+enum Permission {
+  NONE = 'NONE',        // No access
+  USER = 'USER',        // Basic user access
+  ADMIN = 'ADMIN',      // Admin access
+  SUPER = 'SUPER'       // Super admin access
+}
+```
+
+**Example Checks:**
+
+```typescript
+// Single permission check
+hasPermission(UserModule.PMO, Permission.ADMIN)
+
+// Multiple permission check (OR logic)
+hasPermission(UserModule.PMO, Permission.ADMIN, Permission.SUPER)
+
+// Route-level guard
+definePageMeta({
+  accessGuard: {
+    permissions: ['pmo:ADMIN', 'pmo:SUPER']
+  }
+})
+```
+
+---
+
+## 🚀 Performance Optimizations
+
+### 1. Auto-imports
+
+**Configuration:**
+```typescript
+// nuxt.config.ts
+imports: {
+  dirs: ['./constants', './loaders', './helpers', './types']
+}
+```
+
+**Benefits:**
+- Smaller bundle size (tree-shaking)
+- Better DX (no import statements)
+- Faster compilation
+
+### 2. Component Auto-registration
+
+All components in `app/components/` are automatically registered:
+
+```vue
+<!-- No import needed -->
+<StatusBox />
+<InfoItemList />
+<ButtonActionIcon />
+```
+
+### 3. Lazy Loading
+
+```typescript
+// Lazy load heavy components
+const HeavyChart = defineAsyncComponent(() => 
+  import('./components/HeavyChart.vue')
+)
+```
+
+### 4. State Caching
+
+```typescript
+// useAuth caches user data for 1 minute
+const isShouldFetch = () => {
+  if (!value.value || !timestamp.value) return true
+  return Date.now() - timestamp.value > 1000 * 60 * 1
+}
+```
+
+---
+
+## 🧪 Testing Strategy
+
+### Component Testing
+
+```typescript
+import { mount } from '@nuxt/test-utils'
+import StatusBox from '~/components/StatusBox.vue'
+
+describe('StatusBox', () => {
+  it('shows loading state', () => {
+    const wrapper = mount(StatusBox, {
+      props: {
+        status: { isLoading: true },
+        data: null
+      }
+    })
+    expect(wrapper.find('Loader').exists()).toBe(true)
+  })
+})
+```
+
+### Integration Testing
+
+```typescript
+import { setup, $fetch } from '@nuxt/test-utils'
+
+describe('Auth Flow', () => {
+  await setup({
+    // Test configuration
+  })
+
+  it('redirects unauthenticated users', async () => {
+    const response = await $fetch('/protected-route')
+    expect(response.redirected).toBe(true)
+  })
+})
+```
+
+---
+
+## 📊 State Management
+
+### Pinia Stores
+
+```typescript
+// Defined inline in composables
+const me = defineStore('auth.me', () => {
+  const value = ref<IUser | null>(null)
+  const timestamp = ref<number | null>(null)
+
+  const set = (user: IUser | null) => {
+    value.value = user
+  }
+
+  return { value, set, timestamp }
+})()
+```
+
+**Benefits:**
+- Composition API style
+- TypeScript support
+- Devtools integration
+- SSR-friendly
+
+---
+
+## 🎯 Design Patterns
+
+### 1. Composable Pattern
+
+**Purpose:** Reusable stateful logic
+
+```typescript
+export const useAuth = () => {
+  // State
+  const token = useCookie('token')
+  
+  // Computed
+  const isAuthenticated = computed(() => !!token.value)
+  
+  // Methods
+  const login = () => { /* ... */ }
+  
+  return { token, isAuthenticated, login }
+}
+```
+
+### 2. Provider Pattern
+
+**Purpose:** Dependency injection
+
+```typescript
+export const useRequestOptions = () => {
+  const config = useRuntimeConfig()
+  
+  const auth = () => ({
+    baseURL: config.public.baseAPI,
+    headers: {
+      Authorization: `Bearer ${useAuth().token.value}`
+    }
+  })
+  
+  return { auth, base, mock, file }
+}
+```
+
+### 3. Slot Pattern
+
+**Purpose:** Flexible component composition
+
+```vue
+<StatusBox :status="status" :data="data">
+  <template #default="{ data }">
+    <!-- Custom rendering with data -->
+  </template>
+</StatusBox>
+```
+
+### 4. Middleware Chain Pattern
+
+**Purpose:** Sequential request processing
+
+```typescript
+// Middleware executes in order
+export default defineNuxtConfig({
+  router: {
+    middleware: ['common', 'auth', 'permissions']
+  }
+})
+```
+
+---
+
+## 🔧 Configuration Management
+
+### App Config
+
+```typescript
+// app/app.config.ts
+export default defineAppConfig({
+  core: {
+    is_thai_year: false,
+    date_format: 'dd MMM yyyy',
+    color: '#335AFF',
+    limit_per_page: 10,
+    locale: 'en'
+  },
+  ui: {
+    // Nuxt UI customization
+  }
+})
+```
+
+### Runtime Config
+
+```typescript
+// Access in components
+const config = useRuntimeConfig()
+config.public.baseAPI
+```
+
+---
+
+## 📈 Scalability Considerations
+
+### 1. Module Federation
+- Each feature can be a separate module
+- Lazy load modules on demand
+- Independent deployment possible
+
+### 2. Code Splitting
+- Route-based splitting (automatic)
+- Component-based splitting (manual)
+- Vendor chunk optimization
+
+### 3. Caching Strategy
+- User data cached for 1 minute
+- Static assets cached indefinitely
+- API responses cached per request
+
+---
+
+## 🔍 Debugging Guide
+
+### Common Issues
+
+1. **Auto-import not working**
+   - Check `nuxt.config.ts` imports configuration
+   - Restart dev server
+   - Check file location
+
+2. **Middleware not executing**
+   - Check middleware order
+   - Verify route meta configuration
+   - Check return values
+
+3. **Permission denied**
+   - Verify user access_level
+   - Check permission constants
+   - Review middleware logic
+
+### Debug Tools
+
+```typescript
+// Enable verbose logging
+const auth = useAuth()
+console.log('User:', auth.me.value)
+console.log('Permissions:', auth.me.value?.access_level)
+console.log('Has PMO Admin:', auth.hasPermission(UserModule.PMO, Permission.ADMIN))
+```
+
+---
+
+## 📚 Further Reading
+
+- [Nuxt Layers Documentation](https://nuxt.com/docs/guide/going-further/layers)
+- [Nuxt UI Documentation](https://ui.nuxt.com)
+- [Vue 3 Composition API](https://vuejs.org/guide/extras/composition-api-faq.html)
+- [Pinia Documentation](https://pinia.vuejs.org)
+
+---
+
+**Last Updated:** 2025-11-07  
+**Version:** 0.2.50
+

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.2.51](https://gitlab.finema.co/finema/finework/finework-frontend-layer/compare/0.2.50...0.2.51) (2025-11-11)
+
+### Bug Fixes
+
+* update sidebar navigation and breadcrumb rootpath ([1cbdcf1](https://gitlab.finema.co/finema/finework/finework-frontend-layer/commit/1cbdcf135c35bff66c70a71831193255ea5d302b))
+
 ## [0.2.50](https://gitlab.finema.co/finema/finework/finework-frontend-layer/compare/0.2.49...0.2.50) (2025-11-07)
 
 ## [0.2.49](https://gitlab.finema.co/finema/finework/finework-frontend-layer/compare/0.2.48...0.2.49) (2025-11-07)