@finema/finework-layer 0.2.50 → 0.2.51

package/@finema finework-layer - LLM Documentation Guide.md

@@ -0,0 +1,566 @@
+# @finema/finework-layer - LLM Documentation Guide
+
+## 📋 Overview
+
+`@finema/finework-layer` is a Nuxt Layer providing reusable components, composables, layouts, and utilities for Finework applications. This layer extends `@finema/core` and provides enterprise-level features for building internal tools.
+
+**Version:** 0.2.50  
+**Framework:** Nuxt 4.x  
+**UI Library:** @nuxt/ui (Nuxt UI v3)  
+**Package Manager:** pnpm/bun
+
+---
+
+## 🏗️ Project Structure
+
+```
+finework-frontend-layer/
+├── app/
+│   ├── components/          # Reusable Vue components
+│   │   ├── Button/         # Button variants
+│   │   ├── Layout/         # Layout components (Admin, User)
+│   │   ├── InfoItemList.vue
+│   │   └── StatusBox.vue
+│   ├── composables/        # Vue composables
+│   │   ├── useAuth.ts      # Authentication logic
+│   │   └── useRequestOptions.ts
+│   ├── constants/          # Constants and configurations
+│   │   └── routes.ts       # Route definitions
+│   ├── middleware/         # Route middleware
+│   │   ├── auth.ts         # Authentication guard
+│   │   ├── permissions.ts  # Permission-based access
+│   │   ├── guest.ts        # Guest-only routes
+│   │   └── common.ts       # Common middleware
+│   ├── assets/css/         # Global styles
+│   └── app.config.ts       # App configuration
+├── .playground/            # Development playground
+├── nuxt.config.ts          # Nuxt layer configuration
+└── package.json
+```
+
+---
+
+## 🎯 Core Concepts
+
+### 1. **Nuxt Layer Architecture**
+
+This is a **Nuxt Layer**, not a standalone application. It's designed to be extended by other Nuxt projects:
+
+```typescript
+// In consuming project's nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@finema/finework-layer']
+})
+```
+
+### 2. **Auto-imports**
+
+The layer auto-imports from these directories:
+- `./constants` - Route definitions, enums
+- `./loaders` - Data loaders
+- `./helpers` - Utility functions
+- `./types` - TypeScript types
+
+### 3. **Dependency Chain**
+
+```
+Your App → @finema/finework-layer → @finema/core → @nuxt/ui
+```
+
+---
+
+## 🔐 Authentication System
+
+### useAuth Composable
+
+The `useAuth()` composable provides complete authentication functionality:
+
+```typescript
+const auth = useAuth()
+
+// Properties
+auth.token              // Cookie-based auth token
+auth.isAuthenticated    // Computed boolean
+auth.me.value          // Current user object (IUser)
+
+// Methods
+auth.loginSlack()      // Slack OAuth login
+auth.loginMs()         // Microsoft OAuth login
+auth.fetchMe.run()     // Fetch current user
+auth.updateMe.run()    // Update user profile
+auth.hasPermission(module, ...permissions)  // Check permissions
+auth.isSuperAdmin      // Check if super admin
+auth.menusNavbar       // Navigation menu items
+```
+
+### User Interface
+
+```typescript
+interface IUser {
+  id: string
+  email: string
+  full_name: string
+  display_name: string
+  position: string
+  team: ITeam
+  team_code: string
+  avatar_url: string
+  company: string
+  access_level: IUserAccessLevel
+  is_active: boolean
+  joined_date: string
+  slack_id: string
+  created_at: string
+  updated_at: string
+}
+
+interface IUserAccessLevel {
+  used_id: string
+  pmo: Permission.USER | Permission.ADMIN | Permission.SUPER
+  clockin: Permission.USER | Permission.ADMIN
+  timesheet: Permission.USER | Permission.ADMIN
+  setting: Permission.USER | Permission.SUPER
+}
+
+enum Permission {
+  USER = 'USER',
+  ADMIN = 'ADMIN',
+  SUPER = 'SUPER',
+  NONE = 'NONE'
+}
+
+enum UserModule {
+  CHECKIN = 'clockin',
+  PMO = 'pmo',
+  TIMESHEET = 'timesheet',
+  SETTING = 'setting'
+}
+```
+
+### Permission Checking
+
+```typescript
+// Check if user has permission
+if (auth.hasPermission(UserModule.PMO, Permission.ADMIN, Permission.SUPER)) {
+  // User has PMO admin or super permission
+}
+
+// In route meta
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['pmo:ADMIN', 'pmo:SUPER'],
+    redirectTo: '/unauthorized'
+  }
+})
+```
+
+---
+
+## 🛣️ Routing & Middleware
+
+### Route Constants
+
+All routes are defined in `app/constants/routes.ts`:
+
+```typescript
+import { routes } from '#imports'
+
+// Usage
+navigateTo(routes.home.to)
+navigateTo(routes.pmo.project.projects.to)
+```
+
+### Available Middleware
+
+1. **auth.ts** - Requires authentication
+2. **guest.ts** - Guest-only (redirects authenticated users)
+3. **permissions.ts** - Permission-based access control
+4. **common.ts** - Common logic (user fetching)
+
+```typescript
+// Page with auth + permissions
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['clockin:ADMIN'],
+    redirectTo: '/unauthorized'
+  }
+})
+```
+
+---
+
+## 🎨 Components
+
+### 1. StatusBox
+
+Handles loading, error, and empty states:
+
+```vue
+<template>
+  <StatusBox :status="loader.status.value" :data="loader.data.value">
+    <template #default="{ data }">
+      <!-- Your content with data -->
+      <div>{{ data.name }}</div>
+    </template>
+  </StatusBox>
+</template>
+
+<script setup lang="ts">
+const loader = useObjectLoader<MyData>({
+  method: 'GET',
+  url: '/api/data',
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(() => loader.run())
+</script>
+```
+
+### 2. InfoItemList
+
+Display key-value information lists:
+
+```vue
+<template>
+  <InfoItemList
+    :items="[
+      { label: 'Name', value: user.full_name },
+      { label: 'Email', value: user.email },
+      { label: 'Position', value: user.position },
+      { label: 'Active', value: user.is_active, type: 'boolean' },
+      { 
+        label: 'Description', 
+        value: longText, 
+        max: 100  // Truncate with "show more"
+      }
+    ]"
+    :vertical="false"
+    :inline="false"
+  />
+</template>
+```
+
+**Props:**
+- `items` - Array of info items
+- `vertical` - Stack items vertically (default: false = 2 columns)
+- `inline` - Display label and value inline (default: false)
+- `customClass` - Additional CSS classes
+
+**Item Types:**
+- `text` (default)
+- `number`
+- `currency`
+- `date`
+- `date_time`
+- `boolean` - Shows checkbox
+
+### 3. Button Components
+
+#### ActionIcon
+
+```vue
+<ButtonActionIcon
+  icon="ph:pencil-simple"
+  color="primary"
+  :to="`/edit/${id}`"
+  @click="handleEdit"
+/>
+```
+
+#### Back Button
+
+```vue
+<ButtonBack
+  label="กลับไปหน้าหลัก"
+  :to="routes.home.to"
+/>
+```
+
+---
+
+## 🎨 Layouts
+
+### Admin Layout
+
+Full-featured admin layout with sidebar navigation:
+
+```vue
+<template>
+  <LayoutAdmin
+    label="Admin Panel"
+    :items="navigationItems"
+  >
+    <!-- Your page content -->
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+import type { NavigationMenuItem } from '@nuxt/ui'
+
+const navigationItems: NavigationMenuItem[] = [
+  {
+    label: 'Dashboard',
+    icon: 'i-heroicons-home',
+    to: '/admin/dashboard'
+  },
+  {
+    label: 'Users',
+    icon: 'i-heroicons-users',
+    children: [
+      { label: 'All Users', to: '/admin/users' },
+      { label: 'Add User', to: '/admin/users/new' }
+    ]
+  }
+]
+</script>
+```
+
+### User Layout
+
+Simple user-facing layout:
+
+```vue
+<template>
+  <LayoutUser>
+    <!-- Your page content -->
+  </LayoutUser>
+</template>
+```
+
+---
+
+## 🔧 Composables
+
+### useRequestOptions
+
+Provides pre-configured Axios request options:
+
+```typescript
+const { auth, base, mock, file } = useRequestOptions()
+
+// Authenticated request
+const loader = useObjectLoader({
+  method: 'GET',
+  url: '/api/protected',
+  getRequestOptions: auth  // Adds Authorization header
+})
+
+// Public request
+const publicLoader = useObjectLoader({
+  method: 'GET',
+  url: '/api/public',
+  getRequestOptions: base
+})
+
+// File upload
+const fileLoader = useObjectLoader({
+  method: 'POST',
+  url: '/upload',
+  getRequestOptions: file
+})
+```
+
+---
+
+## 📝 Best Practices for LLM Code Generation
+
+### 1. **Always Use Existing Patterns**
+
+✅ **DO:**
+```typescript
+// Use existing composables
+const auth = useAuth()
+const { auth: authOptions } = useRequestOptions()
+
+// Use existing components
+<StatusBox :status="loader.status.value" :data="loader.data.value">
+```
+
+❌ **DON'T:**
+```typescript
+// Don't create custom auth logic
+const token = useCookie('my-token')
+const user = ref(null)
+```
+
+### 2. **Follow Component Conventions**
+
+✅ **DO:**
+```vue
+<script setup lang="ts">
+// TypeScript with proper types
+interface Props {
+  title: string
+  items: MyItem[]
+}
+
+const props = defineProps<Props>()
+const emit = defineEmits<{
+  update: [value: string]
+}>()
+</script>
+```
+
+### 3. **Use Auto-imported Constants**
+
+```typescript
+// These are auto-imported
+import { routes, UserModule, Permission } from '#imports'
+
+// Navigate using route constants
+navigateTo(routes.pmo.project.projects.to)
+```
+
+### 4. **Leverage @finema/core**
+
+This layer extends `@finema/core` which provides:
+- `useObjectLoader` - Data fetching
+- `useListLoader` - List/pagination
+- `useForm` - Form handling with validation
+- UI components from @nuxt/ui
+
+---
+
+## 🎯 Common Patterns
+
+### Pattern 1: Protected Page with Data Loading
+
+```vue
+<template>
+  <LayoutAdmin label="Projects" :items="navItems">
+    <StatusBox :status="projects.status.value" :data="projects.data.value">
+      <template #default="{ data }">
+        <div v-for="project in data" :key="project.id">
+          {{ project.name }}
+        </div>
+      </template>
+    </StatusBox>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['pmo:USER', 'pmo:ADMIN']
+  }
+})
+
+const projects = useListLoader({
+  method: 'GET',
+  url: '/api/projects',
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(() => projects.run())
+</script>
+```
+
+### Pattern 2: Form with Validation
+
+```typescript
+import * as v from 'valibot'
+import { toTypedSchema } from '@vee-validate/valibot'
+
+const form = useForm({
+  validationSchema: toTypedSchema(
+    v.object({
+      name: v.pipe(v.string(), v.minLength(3)),
+      email: v.pipe(v.string(), v.email()),
+      status: v.optional(v.string(), '')
+    })
+  )
+})
+```
+
+---
+
+## 🚀 Development Workflow
+
+### Running the Playground
+
+```bash
+pnpm dev          # Start development server
+pnpm build        # Build for production
+pnpm lint         # Run ESLint
+pnpm lint:fix     # Fix linting issues
+```
+
+### Creating New Components
+
+1. Add to `app/components/`
+2. Use TypeScript with proper types
+3. Follow existing naming conventions
+4. Auto-imported, no need to import manually
+
+### Adding New Routes
+
+1. Define in `app/constants/routes.ts`
+2. Add middleware if needed
+3. Use in components via `routes.your.route.to`
+
+---
+
+## 📚 Additional Resources
+
+- **Nuxt UI Docs:** https://ui.nuxt.com
+- **Nuxt 3 Docs:** https://nuxt.com
+- **@finema/core:** Internal package (check documentation)
+
+---
+
+## ⚠️ Important Notes for LLM
+
+1. **This is a Nuxt Layer** - Not a standalone app
+2. **Auto-imports are enabled** - No need to import components, composables, or constants
+3. **TypeScript is required** - Always use proper types
+4. **Follow existing patterns** - Don't reinvent the wheel
+5. **Use @nuxt/ui components** - Button, Card, Modal, etc.
+6. **Respect permission system** - Always check permissions for protected features
+7. **Use route constants** - Never hardcode routes
+
+---
+
+## 🔍 Quick Reference
+
+### Most Used Imports (Auto-imported)
+
+```typescript
+// Composables
+useAuth()
+useRequestOptions()
+useApp()
+useForm()
+useObjectLoader()
+useListLoader()
+
+// Constants
+routes
+Permission
+UserModule
+
+// Components (no import needed)
+<StatusBox />
+<InfoItemList />
+<ButtonActionIcon />
+<ButtonBack />
+<LayoutAdmin />
+<LayoutUser />
+```
+
+### Environment Variables
+
+```typescript
+const config = useRuntimeConfig()
+
+config.public.baseAPI      // API base URL
+config.public.baseAPIMock  // Mock API URL
+```
+
+---
+
+**Last Updated:** 2025-11-07  
+**Maintained by:** Finema Team
+