| name | thanhnh-dev |
| description | Hỗ trợ toàn bộ quy trình phát triển và migration từ WordPress sang stack AdonisJS v6 (API) + Next.js 15 (FE) + Next.js/React Query/Zustand (CMS) + Golang/Gin (CDN) cho dự án thanhnh.id.vn — website cá nhân chuyên lưu trữ tài liệu kỹ thuật (SysAdmin, DevOps, Development), giới thiệu portfolio dự án và mời chào khách hàng thuê dịch vụ lập trình web. Sử dụng skill này khi làm việc với BẤT KỲ thành phần nào trong dự án thanhnh.id.vn bao gồm API (AdonisJS v6/Lucid ORM/MariaDB), FE (Next.js 15/Tailwind CSS v4), CMS (Next.js/React Query/Zustand), CDN (Golang/Gin), hoặc khi cần hướng dẫn migration nội dung từ WordPress. Trigger khi user nhắc đến: thanhnh, new_site, wordpress migration, API endpoint, Next.js page, Lucid model, AdonisJS, MariaDB, node ace, tài liệu kỹ thuật, portfolio, CDN upload, Go handler, Gin route, CMS, admin panel, quản trị, React Query, Zustand. |
thanhnh.id.vn Development Skill
Skill này hướng dẫn toàn bộ quy trình phát triển thanhnh.id.vn — hệ thống thay thế WordPress gồm 4 dự án chính:
- API — Backend REST API: AdonisJS v6, Lucid ORM, MariaDB → Đọc
references/api.md
- FE — Giao diện người dùng: Next.js 15 (App Router), Tailwind CSS v4, Framer Motion → Đọc
references/fe.md
- CMS — Trang quản trị (Admin): Next.js, React Query, Zustand → Đọc
references/cms.md
- CDN — Dịch vụ CDN hiệu năng cao: Golang, Gin, local storage → Đọc
references/cdn.md
🔗 Repository Links
🗺 Kiến trúc Tổng thể
thanhnh.id.vn/
├── api/ # AdonisJS v6 + Lucid ORM + MariaDB
│ ├── app/
│ │ ├── controllers/ # HTTP Controllers
│ │ ├── models/ # Lucid Models (Active Record)
│ │ ├── middleware/ # Auth, RateLimit, ...
│ │ └── validators/ # VineJS schemas
│ ├── config/
│ │ ├── database.ts # MariaDB connection config
│ │ └── auth.ts
│ ├── database/
│ │ ├── migrations/ # Lucid migration files
│ │ └── seeders/ # Seed data
│ ├── start/
│ │ ├── routes.ts # Route definitions
│ │ └── kernel.ts # Middleware stack
│ ├── .env
│ └── package.json
│
├── fe/ # Next.js 15 App Router + Tailwind CSS v4
│ ├── src/
│ │ ├── app/
│ │ ├── components/
│ │ │ ├── ui/ # Atomic components
│ │ │ └── shared/ # Reusable sections
│ │ ├── hooks/
│ │ ├── lib/
│ │ └── types/
│ ├── public/
│ ├── .env.local
│ └── package.json
│
├── cms/ # Next.js + React Query + Zustand (Admin)
│ ├── src/
│ │ ├── app/ # App Router pages
│ │ ├── components/
│ │ │ ├── ui/ # Atomic components (Button, Input, Tag...)
│ │ │ └── shared/ # Reusable sections
│ │ ├── hooks/
│ │ │ ├── queries/ # useQuery hooks
│ │ │ └── mutations/ # useMutation hooks
│ │ ├── lib/ # API client, error-handler, utils
│ │ ├── stores/ # Zustand stores
│ │ └── types/ # TypeScript types
│ ├── public/
│ ├── .env.local
│ └── package.json
│
└── cdn/ # Golang + Gin (ĐÃ CÓ SẴN)
├── main.go # Entry point, routes
├── config/config.go # Env loading
├── handlers/ # Upload, Image, Folder, File, Middleware
├── utils/utils.go # Helper functions
├── tests/ # Integration tests
├── go.mod
└── .env
🔑 Domain Model
Content
- Post: title, slug, content (Markdown), excerpt, status, views, publishedAt
- Category: SysAdmin / DevOps / Development / Tools / Security…
- Tag: nhãn phân loại nhanh (many-to-many với Post)
- Series: chuỗi bài (e.g. "Kubernetes từ A-Z")
Portfolio
- Project: title, slug, description, techStack (JSON), demoUrl, repoUrl, thumbnail, featured, status
- Service: tên dịch vụ, features (JSON), priceRange, category, featured
Engagement
- ContactRequest: name, email, company, message, serviceId?, status
- Newsletter: email, active
📋 Quy tắc bất biến (Toàn bộ dự án)
🧪 Quy trình Kiểm thử & Commit (BẮT BUỘC)
- Luôn có file test: Mọi feature mới hoặc bug fix ĐỀU PHẢI có file test tương ứng.
- Pass Test trước khi Commit: KHÔNG commit hoặc push code nếu chưa pass toàn bộ test suite của project đó.
🖼️ Media & Upload Standards (Toàn dự án)
- Centralized Upload: Mọi hành động upload file ĐỀU PHẢI thông qua API Media chuyên dụng (
/admin/media/upload).
- Business Controllers: Các business controller (như
CategoriesController, PostsController) TUYỆT ĐỐI KHÔNG xử lý file upload trực tiếp. Chúng chỉ nhận chuỗi URL/Path từ frontend.
- Two-Step Upload Flow: Frontend thực hiện upload file lên Media API trước → nhận về URL → sau đó mới gửi URL này kèm theo payload nghiệp vụ đến business API.
- Image Display: Luôn dùng helper
absoluteCdnUrl (trong CMS) hoặc logic tương đương để hiển thị ảnh. Helper này chịu trách nhiệm gắn thêm CDN URL nếu đường dẫn trong DB là tương đối.
- CDN Folder: Phân loại ảnh theo module tương ứng (ví dụ:
Categories, Posts, Settings) khi upload để quản lý tập trung.
API (AdonisJS v6)
- MariaDB Local: host:
192.168.11.254, user: thanhnh.id.vn, pass: thanhnh.id.vn, db: thanhnh.id.vn.
- Auto-increment ID — TUYỆT ĐỐI KHÔNG sử dụng UUID. Luôn dùng auto-increment ID (
table.increments('id').primary()) cho mọi model. ID type là number, không phải string.
- JSON Array fields — Dùng Lucid
column({ prepare, consume }) để auto serialize/deserialize. KHÔNG để raw JSON string lọt ra response.
- Soft delete — Mọi query list PHẢI filter
.whereNull('deleted_at') hoặc dùng scope.
- Validator — Dùng VineJS (
vine.compile). Không import Zod.
- Relations — Luôn dùng
.preload() khi cần data liên quan. Không query thủ công bằng raw ID.
- Swagger — Mọi bộ CRUD sau khi hoàn thiện PHẢI được bổ sung vào Swagger documentation. Truy cập tại
/swagger.
- ACL Sync — Sau khi thêm module hoặc permission mới vào
ACL_MODULES, PHẢI chạy node ace sync:permissions để cập nhật database.
- Seeding —
AclSeeder chịu trách nhiệm đồng bộ quyền, khởi tạo role và tạo admin mặc định. Luôn chạy seeder này khi setup môi trường mới.
FE (Next.js 15)
- KHÔNG glassmorphism — Border + flat color tuyệt đối.
- Shadow tối đa
shadow-sm, border radius: rounded-lg card / rounded-md button.
- Hover: reverse-color hoặc border-color swap — cấm
hover:scale-*
- Ưu tiên Server Components —
'use client' chỉ khi cần state/event.
- ISR/SSG cho trang tài liệu (
revalidate: 60). SSR chỉ cho data real-time.
- SEO bắt buộc mọi page:
metadata, một <h1> duy nhất, semantic HTML.
- Tools Page Standards:
- Layout: Max-width
1600px, sidebar navigation bên trái với danh mục có thể thu gọn/mở rộng.
- Title: Dùng
break-words để tránh tràn khi resize màn hình.
- Result Boxes: LUÔN hiển thị (không ẩn khi chưa có input), dùng
placeholder text, min-h-[2.5rem] cho consistent sizing.
- Copy Buttons: Nút copy CHỈ dùng icon (không kèm text), đặt tại góc trên bên phải của container chứa kết quả (
absolute right-3 top-3). Khi click phải chuyển sang icon check để phản hồi người dùng.
- Two-Column Layout: Tools có cả Encrypt và Decrypt phải dùng
grid md:grid-cols-2 thay vì toggle buttons.
- Category Order: "Crypto" category luôn đứng đầu (sortOrder 1-10), gộp tất cả các công cụ Generator vào "Crypto".
- Tool Behavior: Phải bấm nút Generate/Refresh/Convert mới hiển thị kết quả (TUYỆT ĐỐI KHÔNG tự động chạy khi mount).
- Action Buttons: Các nút bấm hành động (Generate, Refresh, Convert...) phải được đặt PHÍA TRÊN ô hiển thị kết quả (Result Box).
CMS (Next.js + React Query + Zustand)
- Botble CMS UI Standard — Giao diện PHẢI mô phỏng phong cách Botble CMS:
CDN (Golang)
- Module name:
thanhnh/cdn (cần refactor từ meditour/cdn).
- Auth qua
X-API-KEY header.
- File lưu theo cấu trúc
YYYY/MM/DD/uuid.ext.
- Image processing on-the-fly với cache:
?w=300&h=200&fmt=webp.
- Deep inspection (magic bytes) cho security.
🔄 Migration từ WordPress
Export
wp export --path=/var/www/wordpress --dir=/tmp/wp-export
Field Mapping
| WordPress field | MariaDB column |
|---|
| post_title | title |
| post_name | slug |
| post_content | content |
| post_excerpt | excerpt |
| post_date | published_at |
| post_status=publish | status='PUBLISHED' |
| category | category_id (lookup) |
| tags | post_tags (sync) |
SEO Redirects (fe/next.config.ts)
redirects: async () => [
{ source: '/:year(\\d{4})/:month(\\d{2})/:day(\\d{2})/:slug', destination: '/docs/:slug', permanent: true },
{ source: '/category/:cat', destination: '/docs?category=:cat', permanent: true },
{ source: '/?p=:id', destination: '/', permanent: true },
]
📋 Checklist trước khi Deploy
API:
FE:
CMS:
CDN:
📚 Reference Files
Khi cần chi tiết implementation cho từng component, đọc file tương ứng:
references/api.md — Chi tiết AdonisJS v6: Lucid Models, Migrations, Controllers, Validators, Routes, Seeders, node ace commands
references/fe.md — Chi tiết Next.js 15: Design System, Components, Hooks, SEO, App Router structure
references/cms.md — Chi tiết CMS: Quy trình tạo Module, Atomic Components, React Query/Zustand patterns, UI Standards
references/cdn.md — Chi tiết Golang CDN: Gin routes, Handlers, Config, Image processing, Middleware, Testing