Cấu trúc thư mục dự án Front-End với Next.js App Router: Chuẩn Enterprise & Dễ scale

my-next-app/
├── app/                           # 🌐 TẦNG ĐỊNH TUYẾN MỎNG (Thin Routing Layer)
│   ├── [locale]/                  # Hỗ trợ i18n đa ngôn ngữ (nếu có)
│   │   ├── layout.tsx             # Root layout: Fonts, Providers, Metadata
│   │   ├── page.tsx               # Trang chủ: Re-export từ @/src/features/home
│   │   ├── blog/
│   │   │   ├── page.tsx           # Re-export @/src/features/blog
│   │   │   └── [slug]/page.tsx    # Re-export @/src/features/blog/components/Detail
│   │   ├── dashboard/
│   │   │   └── page.tsx           # Re-export @/src/features/dashboard
│   │   └── not-found.tsx          # Trang 404
│   ├── api/                       # Next.js Route Handlers (REST / Webhooks)
│   │   ├── contact/route.ts
│   │   └── webhooks/route.ts
│   ├── robots.ts                  # SEO robots
│   ├── sitemap.ts                 # Dynamic Sitemap
│   └── globals.css                # Global CSS & Tailwind config
│
├── src/                           # 🧠 TẦNG NGHIỆP VỤ & NGUYÊN BẢN (Business Logic)
│   ├── features/                  # Module nghiệp vụ chia theo tính năng
│   │   ├── auth/                  # Module Authentication
│   │   ├── blog/                  # Module Blog
│   │   │   ├── components/        # Components nội bộ của riêng Blog
│   │   │   │   ├── BlogCard.tsx
│   │   │   │   └── BlogToc.tsx
│   │   │   ├── hooks/             # Hooks nội bộ của Blog
│   │   │   ├── services/          # API queries/mutations của Blog
│   │   │   ├── types/             # Kiểu dữ liệu Blog
│   │   │   └── index.tsx          # Public view / Main feature entry
│   │   └── dashboard/             # Module Dashboard
│   │
│   ├── components/                # UI dùng chung toàn ứng dụng (Shared UI)
│   │   ├── ui/                    # Base primitives (Button, Modal, Input - shadcn)
│   │   ├── layout/                # Header, Footer, Sidebar, Navigation
│   │   ├── feedback/              # Toast, Skeleton, ErrorBoundary, EmptyState
│   │   └── providers/             # React Context & QueryClient Providers
│   │
│   ├── services/                  # Network Layer tập trung
│   │   ├── apiClient.ts           # Axios / Fetch client factory & Interceptors
│   │   └── index.ts               # Barrel export các API client
│   │
│   ├── lib/                       # Cấu hình SDKs & Thư viện bên thứ 3
│   │   ├── supabase/              # Supabase Client & Server helpers
│   │   ├── mongodb/               # Database connection pool
│   │   └── utils.ts               # Helper cn() và các hàm tiện ích chung
│   │
│   ├── hooks/                     # Custom hooks dùng chung toàn dự án
│   │   ├── useMediaQuery.ts
│   │   └── useDebounce.ts
│   │
│   ├── types/                     # TypeScript types toàn cục (Global interfaces)
│   │   └── api.ts
│   │
│   └── constants/                 # Hằng số, config, navigation links
│       └── routes.ts
│
├── public/                        # Static assets (images, fonts, favicons, pdfs)
├── messages/                      # i18n translations (vi.json, en.json)
├── tsconfig.json                  # Path aliases (@/*, @/features/*)
└── next.config.ts                 # Cấu hình Next.js (images, security headers)

import { getPostBySlug } from "@/src/features/blog/services/postService";
import { BlogPostDetail } from "@/src/features/blog";
import { notFound } from "next/navigation";
import type { Metadata } from "next";

interface PageProps {
  params: Promise<{ slug: string; locale: string }>;
}

// 1. Tầng định tuyến khai báo SEO Metadata
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPostBySlug(slug);
  if (!post) return {};

  return {
    title: `${post.title} | Duy Noa`,
    description: post.excerpt,
  };
}

// 2. Page component chỉ đóng vai trò Controller mỏng
export default async function BlogPostPage({ params }: PageProps) {
  const { slug } = await params;
  const post = await getPostBySlug(slug);

  if (!post) {
    notFound();
  }

  // Chuyển toàn bộ việc render UI cho feature component
  return <BlogPostDetail post={post} />;
}

src/features/blog/
├── components/                    # Components nội bộ của riêng Blog
│   ├── BlogCard.tsx               # Card bài viết
│   ├── BlogPostDetail.tsx         # Giao diện chi tiết
│   ├── BlogSearchFilter.tsx       # Thanh tìm kiếm & lọc category
│   └── BlogTableOfContents.tsx    # Mục lục bài viết
├── hooks/                         # Hooks nghiệp vụ nội bộ (useReadingProgress.ts)
├── types/                         # TypeScript interfaces (BlogPost, BlogCategory)
└── index.tsx                      # Main Entry Point export ra ngoài

// src/services/admin/blog/useAdminBlogMutations.ts
"use client";

import { useMutation, useQueryClient } from "@tanstack/react-query";
import { adminBlogApi } from "./adminBlogApi";
import type { CreatePostInput } from "./types";

export function useAdminBlogMutations() {
  const queryClient = useQueryClient();

  const invalidateBlogCache = () => {
    queryClient.invalidateQueries({ queryKey: ["adminPosts"] });
    queryClient.invalidateQueries({ queryKey: ["blogPosts"] });
  };

  const createPost = useMutation({
    mutationFn: (data: CreatePostInput) => adminBlogApi.createPost(data),
    onSuccess: invalidateBlogCache,
  });

  const deletePost = useMutation({
    mutationFn: (id: string) => adminBlogApi.deletePost(id),
    onSuccess: invalidateBlogCache,
  });

  return { createPost, deletePost };
}

// ✅ ĐÚNG: Chỉ cô lập tương tác người dùng vào component con
"use client";

import { useState, useTransition } from "react";
import { useRouter, usePathname } from "next/navigation";

export function BlogSearchFilter() {
  const [term, setTerm] = useState("");
  const [isPending, startTransition] = useTransition();
  const router = useRouter();
  const pathname = usePathname();

  const handleSearch = (e: React.FormEvent) => {
    e.preventDefault();
    startTransition(() => {
      router.push(`${pathname}?q=${encodeURIComponent(term)}`);
    });
  };

  return (
    <form onSubmit={handleSearch} className="relative flex items-center">
      <input
        type="search"
        value={term}
        onChange={(e) => setTerm(e.target.value)}
        placeholder="Tìm kiếm bài viết..."
        className="w-full rounded-xl bg-zinc-900 px-4 py-2 text-zinc-100 placeholder-zinc-500 border border-zinc-800 focus:outline-none focus:border-blue-500"
      />
      {isPending && <span className="text-xs text-zinc-400 ml-2">Đang lọc...</span>}
    </form>
  );
}