moicle 1.4.0 → 1.7.0

package/assets/architecture/react-frontend.md

@@ -1,6 +1,6 @@
 # React Frontend Structure
 
-> MVVM (Model-View-ViewModel) architecture
+> Module-based architecture with hooks + services. Idiomatic React — no MVVM ceremony.
 
 ## Project Structure
 
@@ -13,26 +13,21 @@
 │   │   ├── app.config.ts
 │   │   └── routes.config.ts
 │   ├── core/
-│   │   ├── mvvm/
-│   │   │   └── ViewModel.ts        # ViewModel factory
-│   │   ├── context/                # Global contexts
-│   │   ├── hooks/                  # Core hooks
-│   │   ├── interfaces/             # Core interfaces
-│   │   ├── enums/                  # Core enums
+│   │   ├── context/                # Global contexts (auth, theme)
+│   │   ├── hooks/                  # Core reusable hooks
 │   │   ├── errors/                 # Error handling
 │   │   ├── utils/                  # Core utilities
-│   │   ├── HttpClient.ts           # API client
+│   │   ├── http-client.ts          # API client
 │   │   └── bootstrap.ts            # App initialization
 │   ├── modules/
 │   │   └── {module}/
-│   │       ├── models/             # Types, interfaces, DTOs
-│   │       ├── view-models/        # Hooks (state management)
+│   │       ├── types/              # Types, interfaces, DTOs, schemas
 │   │       ├── services/           # API calls
+│   │       ├── hooks/              # Module hooks (state + data fetching)
 │   │       ├── components/         # Module components
 │   │       ├── pages/              # Page components
 │   │       └── index.ts
 │   ├── lib/                        # Third-party integrations
-│   ├── services/                   # Shared services
 │   ├── utils/                      # Shared utilities
 │   ├── router.tsx                  # Route definitions
 │   ├── index.tsx                   # Entry point
@@ -46,56 +41,60 @@
 └── tailwind.config.js
 ```
 
-## MVVM Pattern
+## Layering
 
 ```
 ┌─────────────────────────────────────────────────┐
-│                    View                          │
-│            (Pages + Components)                  │
+│                  Pages / Components              │
+│                    (render UI)                   │
 ├─────────────────────────────────────────────────┤
-│                 ViewModel                        │
-│          (Hooks - state & logic)                │
+│                      Hooks                       │
+│   (state, queries, mutations, business logic)    │
 ├─────────────────────────────────────────────────┤
-│                   Model                          │
-│           (Types + Services)                    │
+│                     Services                     │
+│                 (pure API calls)                 │
+├─────────────────────────────────────────────────┤
+│                      Types                       │
+│            (models, DTOs, Zod schemas)           │
 └─────────────────────────────────────────────────┘
 ```
 
-**Data flow:**
-1. View renders and uses ViewModel (hook)
-2. ViewModel manages state and calls Services
-3. Services make API calls
-4. Model defines data types
+**Rules:**
+- Components consume hooks, not services directly
+- Hooks orchestrate services + state (TanStack Query, Zustand, useState)
+- Services are pure functions: input → API → output
+- Types are the contract shared across all layers
 
 ## Module Structure
 
 ```
 modules/{module}/
-├── models/
+├── types/
 │   ├── {module}.model.ts          # Types & interfaces
 │   ├── {module}.schema.ts         # Zod schemas (validation)
 │   └── index.ts
-├── view-models/
-│   ├── use-{module}-list.ts       # List ViewModel
-│   ├── use-{module}-form.ts       # Form ViewModel (optional)
-│   └── index.ts
 ├── services/
 │   ├── {module}.service.ts        # API functions
 │   └── index.ts
+├── hooks/
+│   ├── use-{module}-list.ts       # List query hook
+│   ├── use-{module}-detail.ts     # Detail query hook
+│   ├── use-{module}-mutations.ts  # Create/update/delete mutations
+│   └── index.ts
 ├── components/
-│   ├── {Module}Table.tsx
-│   ├── {Module}Modal.tsx
+│   ├── {module}-table.tsx
+│   ├── {module}-form.tsx
 │   └── index.ts
 ├── pages/
-│   ├── {Module}ListPage.tsx
+│   ├── {module}-list-page.tsx
 │   └── index.ts
 └── index.ts
 ```
 
 ## Key Files
 
-### models/user.model.ts
-```tsx
+### types/user.model.ts
+```ts
 export interface User {
   id: string;
   name: string;
@@ -110,8 +109,8 @@ export interface CreateUserRequest {
   password: string;
 }
 
-export interface UserListResponse {
-  data: User[];
+export interface Paginated<T> {
+  data: T[];
   meta: {
     currentPage: number;
     lastPage: number;
@@ -119,150 +118,222 @@ export interface UserListResponse {
     total: number;
   };
 }
+
+export interface UserListParams {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  sort?: { field: keyof User; order: 'asc' | 'desc' };
+}
+```
+
+### types/user.schema.ts
+```ts
+import { z } from 'zod';
+
+export const createUserSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Min 8 characters'),
+});
+
+export type CreateUserFormData = z.infer<typeof createUserSchema>;
 ```
 
 ### services/user.service.ts
-```tsx
-import Client from '@/core/HttpClient';
-import { User, CreateUserRequest } from '../models/user.model';
+```ts
+import { httpClient } from '@/core/http-client';
+import type { User, CreateUserRequest, Paginated, UserListParams } from '../types/user.model';
 
-export const createUser = async (data: CreateUserRequest): Promise<User> => {
-  return await Client.post<User>('/users', {
-    body: JSON.stringify(data),
-  });
+export const userService = {
+  list: (params: UserListParams) =>
+    httpClient.get<Paginated<User>>('/users', { params }),
+
+  detail: (id: string) =>
+    httpClient.get<User>(`/users/${id}`),
+
+  create: (data: CreateUserRequest) =>
+    httpClient.post<User>('/users', data),
+
+  update: (id: string, data: Partial<CreateUserRequest>) =>
+    httpClient.patch<User>(`/users/${id}`, data),
+
+  remove: (id: string) =>
+    httpClient.delete<void>(`/users/${id}`),
+};
+```
+
+### hooks/use-user-list.ts
+```ts
+import { useQuery } from '@tanstack/react-query';
+import { userService } from '../services/user.service';
+import type { UserListParams } from '../types/user.model';
+
+export const userKeys = {
+  all: ['users'] as const,
+  list: (params: UserListParams) => [...userKeys.all, 'list', params] as const,
+  detail: (id: string) => [...userKeys.all, 'detail', id] as const,
 };
 
-export const deleteUser = async (id: string): Promise<void> => {
-  await Client.delete(`/users/${id}`);
+export const useUserList = (params: UserListParams) => {
+  return useQuery({
+    queryKey: userKeys.list(params),
+    queryFn: () => userService.list(params),
+    placeholderData: (prev) => prev,
+  });
 };
 ```
 
-### view-models/use-user-list.ts
-```tsx
-import { User } from '../models/user.model';
-import { listViewModelFactory } from '@/core/mvvm/ViewModel';
-
-export const useUserList = () => {
-  const viewModel = listViewModelFactory<User>(
-    undefined,           // viewModel config
-    '/users',            // API endpoint
-    {},                  // default filters
-    { field: 'name', order: 'asc' }  // default sorter
-  );
+### hooks/use-user-mutations.ts
+```ts
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { userService } from '../services/user.service';
+import { userKeys } from './use-user-list';
+import type { CreateUserRequest } from '../types/user.model';
+
+export const useCreateUser = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: CreateUserRequest) => userService.create(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.all });
+    },
+  });
+};
 
-  return { ...viewModel };
+export const useDeleteUser = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) => userService.remove(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.all });
+    },
+  });
 };
 ```
 
-### pages/UserListPage.tsx
+### pages/user-list-page.tsx
 ```tsx
 import { useState } from 'react';
-import { User } from '../models/user.model';
-import { useUserList } from '../view-models/use-user-list';
-import { UserTable } from '../components/UserTable';
-import { UserModal } from '../components/UserModal';
-
-export const UserListPage: React.FC = () => {
-  const [modalOpen, setModalOpen] = useState(false);
-  const [selectedUser, setSelectedUser] = useState<User | null>(null);
-
-  const {
-    items,
-    isLoading,
-    pagination,
-    handleTableChange,
-    reload,
-    handleInputSearch,
-  } = useUserList();
-
-  const handleEdit = (record: User) => {
-    setSelectedUser(record);
-    setModalOpen(true);
-  };
+import { useUserList } from '../hooks/use-user-list';
+import { useDeleteUser } from '../hooks/use-user-mutations';
+import { UserTable } from '../components/user-table';
+import { UserFormDialog } from '../components/user-form-dialog';
+import type { User } from '../types/user.model';
+
+export default function UserListPage() {
+  const [params, setParams] = useState({ page: 1, pageSize: 20 });
+  const [editing, setEditing] = useState<User | null>(null);
+  const [formOpen, setFormOpen] = useState(false);
+
+  const { data, isLoading } = useUserList(params);
+  const deleteUser = useDeleteUser();
 
   return (
-    <div>
-      <Button onClick={() => { setSelectedUser(null); setModalOpen(true); }}>
-        Add User
-      </Button>
+    <div className="container mx-auto p-6">
+      <div className="flex justify-between mb-6">
+        <h1 className="text-2xl font-bold">Users</h1>
+        <Button onClick={() => { setEditing(null); setFormOpen(true); }}>
+          Add User
+        </Button>
+      </div>
 
       <UserTable
-        dataSource={items}
-        loading={isLoading}
-        pagination={pagination}
-        onChange={handleTableChange}
-        onEdit={handleEdit}
-        onReload={reload}
+        data={data?.data ?? []}
+        meta={data?.meta}
+        isLoading={isLoading}
+        onEdit={(user) => { setEditing(user); setFormOpen(true); }}
+        onDelete={(user) => deleteUser.mutate(user.id)}
+        onPageChange={(page) => setParams((p) => ({ ...p, page }))}
       />
 
-      <UserModal
-        open={modalOpen}
-        onOpenChange={setModalOpen}
-        user={selectedUser}
-        onSuccess={reload}
+      <UserFormDialog
+        open={formOpen}
+        onOpenChange={setFormOpen}
+        user={editing}
       />
     </div>
   );
-};
+}
 ```
 
-### core/HttpClient.ts
-```tsx
+### core/http-client.ts
+```ts
 const BASE_URL = import.meta.env.VITE_API_URL;
 
-const Client = {
-  get: async <T>(url: string): Promise<T> => {
-    const res = await fetch(`${BASE_URL}${url}`, {
-      headers: { 'Authorization': `Bearer ${getToken()}` },
-    });
-    if (!res.ok) throw new Error(res.statusText);
-    return res.json();
-  },
-
-  post: async <T>(url: string, options?: RequestInit): Promise<T> => {
-    const res = await fetch(`${BASE_URL}${url}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${getToken()}`,
-      },
-      ...options,
-    });
-    if (!res.ok) throw new Error(res.statusText);
-    return res.json();
-  },
-
-  delete: async (url: string): Promise<void> => {
-    await fetch(`${BASE_URL}${url}`, {
-      method: 'DELETE',
-      headers: { 'Authorization': `Bearer ${getToken()}` },
+const buildUrl = (path: string, params?: Record<string, unknown>) => {
+  const url = new URL(`${BASE_URL}${path}`);
+  if (params) {
+    Object.entries(params).forEach(([k, v]) => {
+      if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
     });
-  },
+  }
+  return url.toString();
 };
 
-export default Client;
+const request = async <T>(path: string, init: RequestInit & { params?: Record<string, unknown> } = {}): Promise<T> => {
+  const { params, ...rest } = init;
+  const token = getToken();
+  const res = await fetch(buildUrl(path, params), {
+    ...rest,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...rest.headers,
+    },
+  });
+
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new HttpError(res.status, body?.message ?? res.statusText, body);
+  }
+
+  return res.status === 204 ? (undefined as T) : res.json();
+};
+
+export const httpClient = {
+  get:    <T>(path: string, opts?: { params?: Record<string, unknown> }) => request<T>(path, { method: 'GET', ...opts }),
+  post:   <T>(path: string, body?: unknown) => request<T>(path, { method: 'POST', body: JSON.stringify(body) }),
+  patch:  <T>(path: string, body?: unknown) => request<T>(path, { method: 'PATCH', body: JSON.stringify(body) }),
+  put:    <T>(path: string, body?: unknown) => request<T>(path, { method: 'PUT', body: JSON.stringify(body) }),
+  delete: <T>(path: string) => request<T>(path, { method: 'DELETE' }),
+};
 ```
 
+## State Management
+
+Pick the right tool per scope:
+
+| Scope | Tool |
+|-------|------|
+| Server state (API data) | TanStack Query / SWR |
+| Component-local state | `useState` / `useReducer` |
+| Cross-component UI state | Context API |
+| Global client state (cart, filters) | Zustand |
+| Form state | React Hook Form + Zod |
+
+Do NOT dump everything into Redux/Zustand — server state belongs in a query cache.
+
 ## Conventions
 
 | Item | Convention | Example |
 |------|------------|---------|
-| Module folder | kebab-case | `spam-slug/` |
-| Model file | kebab-case.model.ts | `spam-slug.model.ts` |
-| Service file | kebab-case.service.ts | `spam-slug.service.ts` |
-| ViewModel | use-kebab-case.ts | `use-spam-slug-list.ts` |
-| Component | PascalCase.tsx | `SpamSlugTable.tsx` |
-| Page | PascalCasePage.tsx | `SpamSlugListPage.tsx` |
-
-## ViewModel Factory Returns
-
-```tsx
-listViewModelFactory<T>() returns {
-  items: T[],
-  isLoading: boolean,
-  pagination: { current, pageSize, total },
-  handleTableChange: (pagination, filters, sorter) => void,
-  handleInputSearch: (field, value) => void,
-  reload: () => void,
-}
-```
+| Module folder | kebab-case | `user-profile/` |
+| Type file | kebab-case.model.ts | `user.model.ts` |
+| Schema file | kebab-case.schema.ts | `user.schema.ts` |
+| Service file | kebab-case.service.ts | `user.service.ts` |
+| Hook file | use-kebab-case.ts | `use-user-list.ts` |
+| Component file | kebab-case.tsx | `user-table.tsx` |
+| Component export | PascalCase named export | `export const UserTable` |
+| Page file | kebab-case-page.tsx | `user-list-page.tsx` |
+| Page export | default export | `export default UserListPage` |
+
+## Rules
+
+- Components do NOT call services directly — always go through a hook
+- Services are pure: no React, no state, just `fetch` + types
+- Query keys live next to hooks and are exported for invalidation
+- Validate external input at the boundary with Zod — trust types inside the app
+- One module = one feature domain; shared code goes to `core/` or `components/ui/`

package/assets/skills/deep-debug/SKILL.md

@@ -5,110 +5,110 @@ description: Deep bug investigation workflow for hard-to-trace errors. Systemati
 
 # Deep Bug Investigation Workflow
 
-Dành cho bug khó, fix nhiều lần không được. KHÔNG đoán mò — trace từng bước đến root cause.
+For hard bugs that have been "fixed" multiple times without success. DO NOT guess — trace step by step to the root cause.
 
-## Step 1: Thu thập evidence
+## Step 1: Collect evidence
 
-Ghi lại chính xác, KHÔNG diễn giải:
+Record exactly, DO NOT interpret:
 
-- Error message nguyên văn
+- Exact error message
 - Stack trace: file, line number, call chain
-- Environment nào bị (production/staging/local)
-- Lỗi mọi lúc hay chỉ một số case
+- Which environment is affected (production/staging/local)
+- Happens every time or only in certain cases
 
-## Step 2: Verify code đang chạy
+## Step 2: Verify the code that is actually running
 
-KHÔNG giả định code trên production = code trên local.
+DO NOT assume the code on production = the code on local.
 
-- Xác định chính xác version/commit đang deploy
-- So sánh với code đang đọc trên local
-- Nếu KHÁC NHAU → đọc đúng version đang deploy trước khi phân tích tiếp
+- Identify the exact version/commit currently deployed
+- Compare it against the code you are reading locally
+- If they DIFFER → read the deployed version before analyzing further
 
-## Step 3: Trace execution path
+## Step 3: Trace the execution path
 
-Đây là bước quan trọng nhất. Đi từ entry point → đến dòng lỗi. Trace TỪNG bước, KHÔNG nhảy cóc.
+This is the most important step. Go from entry point → to the failing line. Trace EVERY step, DO NOT skip.
 
 ### 3a. Entry point → Error line
 
-- Request/event/job đi vào từ đâu?
-- Function nào gọi function nào? Theo đúng stack trace.
-- Data được truyền qua các layer thế nào?
+- Where does the request/event/job enter from?
+- Which function calls which function? Follow the stack trace exactly.
+- How is data passed through each layer?
 
-### 3b. Data ở dòng lỗi đến từ đâu?
+### 3b. Where does the data at the failing line come from?
 
-- Biến bị lỗi được tạo/load từ đâu?
-- Load trực tiếp từ source (DB, API) hay từ cache/session?
-- Có qua serialize → unserialize không?
-- Có qua transform/convert nào không?
+- Where is the faulty variable created/loaded from?
+- Loaded directly from source (DB, API) or from cache/session?
+- Does it go through serialize → unserialize?
+- Does it go through any transform/convert?
 
-### 3c. Type & state tại thời điểm lỗi
+### 3c. Type & state at the moment of failure
 
-- Type thực tế của biến là gì? (string, object, null, enum...)
-- Code expect type gì?
-- Tại sao type thực tế khác type expected?
+- What is the actual type of the variable? (string, object, null, enum...)
+- What type does the code expect?
+- Why does the actual type differ from the expected one?
 
-### 3d. Framework internals (khi lỗi trong vendor/library)
+### 3d. Framework internals (when the error is inside vendor/library)
 
-- Đọc source code tại ĐÚNG line number từ stack trace
-- Trace ngược: ai gọi method đó, với argument gì
-- Điều kiện nào khiến code đi vào branch gây lỗi
+- Read the source code at the EXACT line number from the stack trace
+- Trace backwards: who calls that method, and with what arguments
+- What condition drives the code into the failing branch
 
-## Step 4: Tìm root cause — Trả lời 3 câu
+## Step 4: Find the root cause — Answer 3 questions
 
-1. **Tại sao lỗi?** — Nguyên nhân kỹ thuật cụ thể
-2. **Tại sao trước đây không lỗi?** — Cái gì thay đổi
-3. **Điều kiện reproduce?** — Khi nào lỗi, khi nào không
+1. **Why does it fail?** — The specific technical cause
+2. **Why didn't it fail before?** — What changed
+3. **Reproduction conditions?** — When it fails, when it doesn't
 
-Nếu chưa trả lời được cả 3 → quay lại Step 3, trace thêm.
+If you can't answer all 3 → go back to Step 3, trace further.
 
-## Step 5: Check các nguồn state ẩn
+## Step 5: Check hidden state sources
 
-Bug "lúc được lúc không" thường do state ẩn. Check theo thứ tự:
+"Sometimes works, sometimes doesn't" bugs are usually caused by hidden state. Check in this order:
 
 ### Cache / Serialization
 
-- Object lấy từ cache có mất internal state không? (transient fields, lazy-loaded properties, runtime caches)
-- Cache cũ chứa data format cũ, code mới expect format mới?
-- Serialize/unserialize có thay đổi type không? (int↔float, null handling, enum↔string)
+- Does the object pulled from cache lose any internal state? (transient fields, lazy-loaded properties, runtime caches)
+- Does stale cache contain the old data format while new code expects the new format?
+- Does serialize/unserialize change the type? (int↔float, null handling, enum↔string)
 
 ### Database / Storage
 
-- Collation, encoding có ảnh hưởng comparison không?
-- Default value trong DB có match code expectation không?
-- Schema đã update trên production chưa?
+- Do collation/encoding affect comparisons?
+- Do default values in the DB match the code's expectations?
+- Has the schema been updated on production yet?
 
 ### Runtime cache / Compiled cache
 
-- Có compiled/cached config, routes, views chưa clear?
-- Bytecode cache (OPcache, compiled assets) có serve file cũ?
-- CDN/proxy cache serve asset cũ?
+- Any compiled/cached config, routes, or views that haven't been cleared?
+- Does the bytecode cache (OPcache, compiled assets) serve the old file?
+- Does CDN/proxy cache serve a stale asset?
 
 ### Environment
 
-- Env vars trên production có đúng/đủ không?
-- Version runtime (PHP, Node, Go, Python, etc.) có khác local không?
-- Dependency version có khác không?
+- Are env vars on production correct/complete?
+- Does the runtime version (PHP, Node, Go, Python, etc.) differ from local?
+- Do dependency versions differ?
 
 ## Step 6: Fix
 
-Chỉ fix khi đã trả lời được 3 câu ở Step 4. Fix phải:
+Only fix once you have answered the 3 questions from Step 4. The fix must:
 
-- Xử lý đúng root cause, không phải symptom
-- Handle edge case đã phát hiện (cache stale, type mismatch)
-- Defensive ở data boundary (cache, DB, external API) — không ở internal logic
-- Không phá code path bình thường để fix edge case
+- Address the root cause, not the symptom
+- Handle the edge case discovered (stale cache, type mismatch)
+- Be defensive at data boundaries (cache, DB, external API) — not in internal logic
+- Not break the normal code path in order to patch an edge case
 
 ## Step 7: Verify
 
-- Reproduce điều kiện lỗi từ Step 4 → confirm đã fix
-- Test code path bình thường vẫn hoạt động
-- Nếu liên quan cache → test cả fresh load lẫn cached load
-- Verify đúng version đã deploy (lặp lại Step 2)
+- Reproduce the failure conditions from Step 4 → confirm the fix works
+- Check the normal code path still works
+- If cache-related → test both fresh load and cached load
+- Verify against the actually deployed version (repeat Step 2)
 
 ## IMPORTANT
 
-- **KHÔNG ĐOÁN MÒ** — Trace evidence, không suy luận từ tên biến hay "có lẽ là..."
-- **KHÔNG FIX TRƯỚC KHI HIỂU** — Fix mà không hiểu root cause = tạo bug mới
-- **VERIFY DEPLOYED CODE** — Luôn check version đang chạy, không giả định production = local
-- **CHECK CACHE TRƯỚC** — Phần lớn bug "lúc được lúc không" là do stale cached state
-- **MỘT ROOT CAUSE** — Mỗi bug chỉ có 1 root cause. Nếu còn nhiều khả năng → trace thêm
+- **DO NOT GUESS** — Trace evidence, do not infer from variable names or "maybe it's..."
+- **DO NOT FIX BEFORE UNDERSTANDING** — Fixing without knowing the root cause = creating a new bug
+- **VERIFY DEPLOYED CODE** — Always check the running version, never assume production = local
+- **CHECK CACHE FIRST** — Most "sometimes works, sometimes doesn't" bugs come from stale cached state
+- **ONE ROOT CAUSE** — Every bug has one root cause. If multiple possibilities remain → trace further