@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/react/datetime-guide.md.stub

@@ -0,0 +1,137 @@
+# DateTime Handling Guide (Frontend)
+
+> **Related:** [README](./README.md) | [Service Pattern](./service-pattern.md) | [Laravel Integration](./laravel-integration.md)
+
+## Golden Rule: "Store UTC, Display Local"
+
+```
+API Response (UTC) → Day.js → Display (Local Timezone)
+User Input (Local) → Day.js → API Request (UTC)
+```
+
+---
+
+## Setup
+
+Day.js is already configured in this project. Import from `@/lib/dayjs`:
+
+```typescript
+import dayjs, { formatDateTime, toUTCString } from "@/lib/dayjs";
+```
+
+> **Rule:** Always import from `@/lib/dayjs`, never from `dayjs` directly.
+
+---
+
+## Usage Patterns
+
+### Display UTC from API
+
+```typescript
+import dayjs, { formatDateTime, formatRelative } from "@/lib/dayjs";
+
+// API returns: "2024-01-15T10:30:00Z" (UTC)
+const createdAt = "2024-01-15T10:30:00Z";
+
+// Using helper functions (recommended)
+formatDateTime(createdAt);        // "2024/01/15 19:30"
+formatRelative(createdAt);        // "3日前"
+
+// Using dayjs directly
+dayjs(createdAt).format("LL");    // "2024年1月15日" (localized)
+```
+
+### Send Local Input as UTC
+
+```typescript
+import dayjs, { toUTCString } from "@/lib/dayjs";
+
+// User selects: 2024/01/15 19:30 (local time)
+const localDate = dayjs("2024-01-15 19:30");
+
+// Convert to UTC for API
+const utcString = toUTCString(localDate);
+// "2024-01-15T10:30:00.000Z"
+```
+
+### With Ant Design DatePicker
+
+```typescript
+import { DatePicker, Form } from "antd";
+import dayjs, { toUTCString, fromUTCString } from "@/lib/dayjs";
+import type { Dayjs } from "@/lib/dayjs";
+
+function MyForm() {
+  const handleSubmit = (values: { date: Dayjs }) => {
+    api.post("/events", { date: toUTCString(values.date) });
+  };
+
+  return (
+    <Form onFinish={handleSubmit}>
+      <Form.Item name="date">
+        <DatePicker showTime />
+      </Form.Item>
+    </Form>
+  );
+}
+
+// Display API date in DatePicker
+<DatePicker defaultValue={fromUTCString(event.scheduled_at)} />
+```
+
+---
+
+## Available Functions
+
+| Function                       | Description           | Example Output               |
+| ------------------------------ | --------------------- | ---------------------------- |
+| `formatDate(utc)`              | Date only             | `"2024/01/15"`               |
+| `formatDateTime(utc)`          | Date + time           | `"2024/01/15 19:30"`         |
+| `formatDateLocalized(utc)`     | Localized date        | `"2024年1月15日"`            |
+| `formatDateTimeLocalized(utc)` | Localized date + time | `"2024年1月15日 19:30"`      |
+| `formatRelative(utc)`          | Relative time         | `"3日前"`                    |
+| `toUTCString(dayjs)`           | Convert to UTC ISO    | `"2024-01-15T10:30:00.000Z"` |
+| `fromUTCString(utc)`           | Parse to Dayjs        | `Dayjs object`               |
+| `nowUTC()`                     | Current UTC time      | `Dayjs object`               |
+| `isPast(utc)`                  | Check if past         | `true/false`                 |
+| `isFuture(utc)`                | Check if future       | `true/false`                 |
+
+---
+
+## Anti-Patterns ❌
+
+```typescript
+// ❌ Import dayjs directly
+import dayjs from "dayjs";
+
+// ❌ Use native Date
+new Date("2024-01-15");
+
+// ❌ Send local date string to API
+api.post({ date: "2024/01/15 19:30" });
+
+// ❌ Use moment.js
+import moment from "moment";
+```
+
+## Correct Patterns ✅
+
+```typescript
+// ✅ Import from lib
+import dayjs, { formatDateTime, toUTCString } from "@/lib/dayjs";
+
+// ✅ Use helper functions
+formatDateTime(user.created_at);
+
+// ✅ Send UTC to API
+api.post({ date: toUTCString(localDate) });
+```
+
+---
+
+## Checklist
+
+- [ ] Import from `@/lib/dayjs`, not `dayjs`
+- [ ] Use helper functions for display
+- [ ] Use `toUTCString()` when sending to API
+- [ ] Use `fromUTCString()` for form default values

package/dist/knowledge/react/design-philosophy.md.stub

@@ -0,0 +1,363 @@
+# Design Philosophy
+
+> This document explains the architectural decisions and design principles for this frontend project.
+
+## Architecture: Clean Architecture + Service Layer
+
+```mermaid
+flowchart TD
+    subgraph UI["UI Layer"]
+        Page["Page (Container)"]
+        Component["Component (Presentational)"]
+    end
+
+    subgraph Hooks["Hooks Layer"]
+        Query["TanStack Query"]
+    end
+
+    subgraph Services["Service Layer"]
+        Service["userService, postService"]
+    end
+
+    subgraph Infra["Infrastructure Layer"]
+        Axios["Axios (lib/api.ts)"]
+    end
+
+    Page --> Query
+    Component --> Page
+    Query --> Service
+    Service --> Axios
+    Axios -->|HTTP| API[Laravel API]
+```
+
+| Layer          | Responsibility                    | Rules                    |
+| -------------- | --------------------------------- | ------------------------ |
+| UI             | Display data, handle interactions | No direct API calls      |
+| Hooks          | Server state, caching, sync       | Uses services            |
+| Service        | API communication                 | No React, pure functions |
+| Infrastructure | HTTP client, interceptors         | Framework-agnostic       |
+
+---
+
+## Why This Architecture?
+
+### 1. Separation of Concerns
+
+Each layer has a single responsibility:
+
+| Layer          | Knows About             | Doesn't Know About     |
+| -------------- | ----------------------- | ---------------------- |
+| UI             | Components, hooks       | HTTP, API endpoints    |
+| Hooks          | Services, query keys    | Axios, response format |
+| Services       | API instance, endpoints | React, components      |
+| Infrastructure | HTTP protocol           | Business logic         |
+
+**Benefit**: Change one layer without affecting others.
+
+### 2. Testability
+
+```typescript
+// Services are pure functions - easy to test
+test("userService.get returns user", async () => {
+  const user = await userService.get(1);
+  expect(user.id).toBe(1);
+});
+
+// Components receive data via props - easy to mock
+test("UserTable renders users", () => {
+  render(<UserTable users={mockUsers} loading={false} />);
+  expect(screen.getByText("John")).toBeInTheDocument();
+});
+```
+
+### 3. Reusability
+
+```typescript
+// Services can be used anywhere
+const user = await userService.get(1);  // In a script
+const { data } = useQuery({ queryFn: () => userService.get(1) });  // In React
+```
+
+### 4. Type Safety
+
+Types flow through layers:
+
+```typescript
+// Omnify generates Model types (synced with DB)
+type User = { id: number; name: string; email: string; }
+
+// Services use Model types + define Input types
+const userService = {
+  get: (id: number): Promise<User> => ...,
+  create: (input: UserCreateInput): Promise<User> => ...,
+}
+
+// Hooks inherit types from services
+const { data } = useQuery<User>({ ... });
+
+// Components receive typed props
+function UserCard({ user }: { user: User }) { ... }
+```
+
+---
+
+## Why TanStack Query?
+
+### Problem: Server State is Different
+
+```typescript
+// ❌ Client state (useState) - you control it
+const [count, setCount] = useState(0);
+setCount(1);  // Immediately updates
+
+// ❌ Server state - you DON'T control it
+const [users, setUsers] = useState([]);
+// What if another user adds a new user?
+// What if the network fails?
+// What if the data is stale?
+```
+
+### Solution: TanStack Query
+
+| Feature            | Without TanStack     | With TanStack                    |
+| ------------------ | -------------------- | -------------------------------- |
+| Loading state      | Manual `useState`    | Automatic `isLoading`            |
+| Error handling     | Try/catch everywhere | Automatic `error`                |
+| Caching            | None or manual       | Automatic, configurable          |
+| Refetching         | Manual               | Automatic on focus/reconnect     |
+| Deduplication      | None                 | Automatic (same key = 1 request) |
+| Optimistic updates | Complex              | Built-in                         |
+
+### TanStack Query vs SWR
+
+| Feature            | TanStack Query              | SWR             |
+| ------------------ | --------------------------- | --------------- |
+| Mutations          | ✅ First-class `useMutation` | ⚠️ Manual        |
+| Devtools           | ✅ Excellent                 | ⚠️ Basic         |
+| Query invalidation | ✅ Granular control          | ⚠️ Limited       |
+| Optimistic updates | ✅ Built-in rollback         | ⚠️ Manual        |
+| Bundle size        | ~13KB                       | ~4KB            |
+| Best for           | Complex apps                | Simple fetching |
+
+**We chose TanStack Query** because:
+- Better mutation support (CRUD apps need this)
+- Granular cache invalidation (important for data consistency)
+- Better devtools for debugging
+
+---
+
+## Why Service Layer?
+
+### Problem: API Calls Scattered
+
+```typescript
+// ❌ API calls in components
+function UserList() {
+  const { data } = useQuery({
+    queryFn: () => axios.get("/api/users").then(r => r.data),
+  });
+}
+
+function UserDetail({ id }) {
+  const { data } = useQuery({
+    queryFn: () => axios.get(`/api/users/${id}`).then(r => r.data.data),
+  });
+}
+// Problems:
+// - Duplicated logic (response unwrapping)
+// - Hard to change API (update every component)
+// - Hard to test (need to mock axios in every test)
+```
+
+### Solution: Service Layer
+
+```typescript
+// ✅ Centralized in service
+const userService = {
+  list: () => api.get("/api/users").then(r => r.data),
+  get: (id) => api.get(`/api/users/${id}`).then(r => r.data.data ?? r.data),
+};
+
+// Components just use services
+function UserList() {
+  const { data } = useQuery({ queryFn: userService.list });
+}
+
+function UserDetail({ id }) {
+  const { data } = useQuery({ queryFn: () => userService.get(id) });
+}
+// Benefits:
+// - Single source of truth for API logic
+// - Easy to change (update one file)
+// - Easy to test (mock service, not axios)
+```
+
+---
+
+## Design Principles
+
+### 1. Single Source of Truth
+
+| Data Type                  | Source                         |
+| -------------------------- | ------------------------------ |
+| Server data (users, posts) | TanStack Query                 |
+| Model types                | Omnify (`@omnify/schemas`)       |
+| Form state                 | Ant Design Form                |
+| UI state (modal open)      | Local `useState`               |
+| Global client state        | Context or Zustand (if needed) |
+
+### 2. Colocation
+
+Keep related code together:
+
+```
+// ✅ Good: Related files together
+services/
+  users.ts         # Service + Input types
+  posts.ts
+
+// ❌ Bad: Types scattered
+types/
+  UserCreateInput.ts
+  UserUpdateInput.ts
+  PostCreateInput.ts
+services/
+  users.ts
+  posts.ts
+```
+
+### 3. Explicit Over Implicit
+
+```typescript
+// ✅ Explicit: Clear what this does
+const { data: users, isLoading, error } = useQuery({
+  queryKey: queryKeys.users.list(filters),
+  queryFn: () => userService.list(filters),
+});
+
+// ❌ Implicit: Magic happening somewhere
+const users = useUsers(filters);  // What's inside? Caching? Error handling?
+```
+
+### 4. Fail Fast
+
+```typescript
+// ✅ Types catch errors at compile time
+const user: User = { id: "1" };  // Error: id should be number
+
+// ✅ ESLint catches bad patterns
+useEffect(() => { fetchData() }, []);  // Warning: use useQuery
+
+// ✅ Runtime errors shown to user
+onError: (error) => form.setFields(getFormErrors(error));
+```
+
+### 5. Composition Over Inheritance
+
+```typescript
+// ✅ Compose small pieces
+function UserPage() {
+  return (
+    <PageLayout>
+      <UserFilters />
+      <UserTable />
+      <UserPagination />
+    </PageLayout>
+  );
+}
+
+// ❌ Don't create giant "smart" components
+function UserPage() {
+  // 500 lines of mixed concerns
+}
+```
+
+---
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Component as Component (UI)
+    participant Mutation as Mutation (TanStack)
+    participant Service as Service
+    participant Axios as Axios (Infra)
+    participant API as Laravel API
+
+    User->>Component: clicks "Save"
+    Component->>Mutation: mutation.mutate(values)
+    Mutation->>Service: userService.create(values)
+    Service->>Axios: api.post("/api/users", values)
+    Axios->>API: HTTP POST
+    API-->>Axios: Response
+    Axios-->>Service: data
+    Service-->>Mutation: User
+    Mutation->>Mutation: invalidateQueries
+    Mutation-->>Component: onSuccess
+    Component-->>User: UI updates
+```
+
+---
+
+## Coding Style: Centralized Configuration
+
+### Rule: One File Per Concern in `lib/`
+
+```
+lib/
+├── api.ts          # Axios config + interceptors + error handling
+├── query.tsx       # QueryClient config + provider
+├── queryKeys.ts    # All query keys
+└── dayjs.ts        # Day.js config + plugins + utilities
+```
+
+**Why single file?**
+- **Consistency**: One place to find all related code
+- **Maintainability**: Easy to update
+- **Discoverability**: Clear what's available
+- **No over-engineering**: Avoid splitting into multiple files unnecessarily
+
+### Anti-Pattern ❌
+
+```
+// Don't split into multiple files unnecessarily
+lib/
+├── dayjs/
+│   ├── config.ts
+│   ├── plugins.ts
+│   ├── locale.ts
+│   └── utils.ts
+```
+
+### Correct Pattern ✅
+
+```
+// Keep related code in one file
+lib/
+└── dayjs.ts        # Config + plugins + locale + utils (all in one)
+```
+
+### When to Split Files
+
+Only split when:
+1. File exceeds ~300-400 lines
+2. Clear separate concerns (e.g., `api.ts` vs `queryKeys.ts`)
+3. Different import patterns needed
+
+---
+
+## Summary
+
+| Aspect       | Choice              | Reason                              |
+| ------------ | ------------------- | ----------------------------------- |
+| Architecture | Clean Architecture  | Separation of concerns, testability |
+| Server State | TanStack Query      | Caching, mutations, devtools        |
+| HTTP Client  | Axios               | Interceptors, Laravel integration   |
+| UI Library   | Ant Design          | Comprehensive, consistent           |
+| Types        | TypeScript + Omnify | Type safety, DB sync                |
+| Styling      | Tailwind CSS        | Utility-first, fast                 |
+| i18n         | next-intl           | Server components support           |
+| Date/Time    | Day.js              | Ant Design compatible, lightweight  |
+
+**Philosophy**: Keep it simple, explicit, and type-safe. Each layer does one thing well.

package/dist/knowledge/react/i18n-guide.md.stub

@@ -0,0 +1,211 @@
+# Internationalization (i18n) Guide
+
+> **Related:** [README](./README.md) | [Ant Design](./antd-guide.md)
+
+This project uses `next-intl` for internationalization.
+
+## Current Locales
+
+| Code | Language   | Default |
+| ---- | ---------- | ------- |
+| ja   | 日本語     | ✅       |
+| en   | English    |         |
+| vi   | Tiếng Việt |         |
+
+---
+
+## Usage
+
+### Basic Translation
+
+```typescript
+import { useTranslations } from "next-intl";
+
+function MyComponent() {
+  const t = useTranslations();
+  
+  return (
+    <Button>{t("common.save")}</Button>
+  );
+}
+```
+
+### With Namespace
+
+```typescript
+const t = useTranslations("messages");
+t("created")  // "作成しました" (ja) | "Created successfully" (en)
+```
+
+### With Parameters
+
+```typescript
+t("validation.minLength", { field: "Password", min: 8 })
+// "Password must be at least 8 characters"
+```
+
+### LocaleSwitcher Component
+
+```typescript
+import LocaleSwitcher from "@/components/LocaleSwitcher";
+
+<LocaleSwitcher />  // Dropdown to switch language
+```
+
+### Get Current Locale
+
+```typescript
+import { useLocale } from "@/hooks/useLocale";
+
+function MyComponent() {
+  const { locale, setLocale, localeNames } = useLocale();
+  // locale: "ja" | "en" | "vi"
+  // setLocale: (locale) => void
+  // localeNames: { ja: "日本語", en: "English", vi: "Tiếng Việt" }
+}
+```
+
+---
+
+## Adding New Language
+
+### Step 1: Create Message File
+
+Create `src/i18n/messages/{locale}.json`:
+
+```json
+{
+  "common": {
+    "save": "저장",
+    "cancel": "취소",
+    "delete": "삭제",
+    "edit": "편집",
+    "create": "만들기",
+    "search": "검색",
+    "loading": "로딩 중...",
+    "noData": "데이터 없음",
+    "confirm": "확인",
+    "back": "뒤로",
+    "next": "다음",
+    "previous": "이전",
+    "submit": "제출",
+    "reset": "초기화",
+    "close": "닫기",
+    "yes": "예",
+    "no": "아니오"
+  },
+  "messages": {
+    "created": "생성되었습니다",
+    "updated": "업데이트되었습니다",
+    "deleted": "삭제되었습니다",
+    "saved": "저장되었습니다",
+    "error": "오류가 발생했습니다",
+    "confirmDelete": "정말 삭제하시겠습니까?",
+    "networkError": "네트워크 오류",
+    "serverError": "서버 오류",
+    "unauthorized": "로그인해 주세요",
+    "forbidden": "접근 권한이 없습니다",
+    "notFound": "찾을 수 없습니다",
+    "sessionExpired": "세션이 만료되었습니다. 페이지를 새로고침해 주세요",
+    "tooManyRequests": "요청이 너무 많습니다. 잠시 기다려 주세요"
+  },
+  "auth": {
+    "login": "로그인",
+    "logout": "로그아웃",
+    "register": "회원가입",
+    "email": "이메일",
+    "password": "비밀번호",
+    "passwordConfirm": "비밀번호 확인",
+    "rememberMe": "로그인 상태 유지",
+    "forgotPassword": "비밀번호를 잊으셨나요?",
+    "resetPassword": "비밀번호 재설정",
+    "loginSuccess": "로그인되었습니다",
+    "logoutSuccess": "로그아웃되었습니다",
+    "registerSuccess": "가입이 완료되었습니다"
+  },
+  "validation": {
+    "required": "{field}은(는) 필수입니다",
+    "email": "유효한 이메일 주소를 입력해 주세요",
+    "minLength": "{field}은(는) {min}자 이상이어야 합니다",
+    "maxLength": "{field}은(는) {max}자 이하여야 합니다",
+    "passwordMatch": "비밀번호가 일치하지 않습니다"
+  },
+  "nav": {
+    "home": "홈",
+    "dashboard": "대시보드",
+    "users": "사용자",
+    "settings": "설정",
+    "profile": "프로필"
+  }
+}
+```
+
+### Step 2: Update Config
+
+Edit `src/i18n/config.ts`:
+
+```typescript
+export const locales = ["ja", "en", "vi", "ko"] as const;  // Add new locale
+
+export const localeNames: Record<Locale, string> = {
+  ja: "日本語",
+  en: "English",
+  vi: "Tiếng Việt",
+  ko: "한국어",  // Add display name
+};
+```
+
+### Step 3: Add Ant Design Locale
+
+Edit `src/components/AntdThemeProvider.tsx`:
+
+```typescript
+import jaJP from "antd/locale/ja_JP";
+import enUS from "antd/locale/en_US";
+import viVN from "antd/locale/vi_VN";
+import koKR from "antd/locale/ko_KR";  // Add import
+
+const antdLocales = {
+  ja: jaJP,
+  en: enUS,
+  vi: viVN,
+  ko: koKR,  // Add mapping
+};
+```
+
+---
+
+## File Structure
+
+```
+src/i18n/
+├── config.ts               # Locales configuration
+├── request.ts              # Server-side locale detection
+├── index.ts                # Exports
+└── messages/
+    ├── ja.json             # Japanese translations
+    ├── en.json             # English translations
+    └── vi.json             # Vietnamese translations
+```
+
+---
+
+## Best Practices
+
+```typescript
+// ✅ DO: Use translation keys
+<Button>{t("common.save")}</Button>
+
+// ❌ DON'T: Hardcode strings
+<Button>保存</Button>
+
+// ✅ DO: Use namespaces for context
+const tAuth = useTranslations("auth");
+const tMessages = useTranslations("messages");
+
+// ✅ DO: Use parameters for dynamic content
+t("validation.minLength", { field: t("auth.password"), min: 8 })
+
+// ❌ DON'T: Concatenate strings
+`${t("auth.password")} must be at least 8 characters`
+```