Imported from TranVanTienDat/Milkyway (apps/cms/.agents/skills/strapi-v5-expert/SKILL.md). Install upstream with npx skills add TranVanTienDat/Milkyway --skill strapi-v5-expert. Copyright stays with the author.

Hướng dẫn cho Agent

Khi người dùng đặt ra một nhiệm vụ, hãy tìm danh mục phù hợp nhất trong phần "Quick Reference" bên dưới. Sao chép URL cần thiết và SỬ DỤNG CÔNG CỤ WEB BROWSING để đọc tài liệu Strapi v5 mới nhất theo liên kết đó. Chỉ sau khi đọc xong mới bắt đầu tạo mã nguồn.

Quick Reference (Chỉ mục Tài liệu)

1. Document Service API (Công cụ chính để làm việc với DB)

Sử dụng các liên kết này cho bất kỳ nhiệm vụ nào liên quan đến các thao tác CRUD ở bẻckend. entityService cũ đã được thay thế bằng strapi.documents().

• Core API & CRUD: https://docs.strapi.io/dev-docs/api/document-service Mô tả: Các phương thức cơ bản (findOne, findMany, create, update, delete, count). Làm việc với documentId.
• Documents Concept: https://docs.strapi.io/dev-docs/api/document-service#documents Mô tả: Khái niệm Document trong Strapi 5 (kết hợp các locales và trạng thái xuất bản vào một đối tượng duy nhất).
• Populate (Liên kết và Media): https://docs.strapi.io/dev-docs/api/document-service/populate Mô tả: Cách truy vấn các liên kết lồng nhau và các file media.
• Fields Selection: https://docs.strapi.io/dev-docs/api/document-service/fields Mô tả: Chọn các cột cụ thể từ DB (tham số fields).
• Filters (Lọc): https://docs.strapi.io/dev-docs/api/document-service/filters Mô tả: Các toán tử lọc ($eq, $in, $not, $and và các toán tử khác).
• Sort & Pagination: https://docs.strapi.io/dev-docs/api/document-service/sort-pagination Mô tả: Sắp xếp theo trường và phân trang (limit, start).
• Locale (i18n): https://docs.strapi.io/dev-docs/api/document-service/locale Mô tả: Thao tác với các tài liệu cho một locale (ngôn ngữ) cụ thể.
• Draft & Publish: https://docs.strapi.io/dev-docs/api/document-service/draft-and-publish Mô tả: Làm việc với các trạng thái (published, draft), các phương thức publish() và unpublish().
• Document Service Middlewares: https://docs.strapi.io/dev-docs/api/document-service/middlewares Mô tả: Đánh chặn và sửa đổi các yêu cầu strapi.documents.use() trước khi truy cập vào DB.

2. Kiến trúc và Tùy chỉnh Backend

• Overview & Structure: https://docs.strapi.io/dev-docs/backend-customization Mô tả: Sơ đồ tương tác của các yêu cầu bẻckend.
• Project Structure: https://docs.strapi.io/dev-docs/project-structure Mô tả: Cấu trúc thư mục của dự án Strapi (src/api, config, v.v.).
• Routes: https://docs.strapi.io/dev-docs/backend-customization/routes Mô tả: Cấu hình các HTTP routes tùy chỉnh và core routes.
• Controllers: https://docs.strapi.io/dev-docs/backend-customization/controllers Mô tả: Tạo các controllers tùy chỉnh và mở rộng (createCoreController).
• Services: https://docs.strapi.io/dev-docs/backend-customization/services Mô tả: Đóng gói logic kinh doanh (createCoreService).
• Middlewares (HTTP): https://docs.strapi.io/dev-docs/backend-customization/middlewares Mô tả: Các middlewares toàn cục và route của Koa (ctx, next).
• Policies: https://docs.strapi.io/dev-docs/backend-customization/policies Mô tả: Bảo vệ các endpoints và kiểm tra quyền truy cập trước khi vào controller.
• Requests & Responses: https://docs.strapi.io/dev-docs/backend-customization/requests-responses Mô tả: Cấu trúc đối tượng ctx (ctx.request, ctx.state.user, ctx.response).
• Error Handling: https://docs.strapi.io/dev-docs/error-handling Mô tả: Ném các lỗi tiêu chuẩn hóa (ApplicationError, ValidationError).
• Lifecycle Functions (Global): https://docs.strapi.io/dev-docs/configurations/functions Mô tả: Sử dụng register, bootstrap và destroy trong file src/index.ts.

3. Models và Cơ sở dữ liệu

• Models & Content-Types: https://docs.strapi.io/dev-docs/backend-customization/models Mô tả: Tạo sơ đồ dữ liệu (schema.json), các kiểu thuộc tính.
• Lifecycle Hooks: https://docs.strapi.io/dev-docs/backend-customization/models#lifecycle-hooks Mô tả: Các triggers của DB (beforeCreate, afterUpdate).
• Relations: https://docs.strapi.io/dev-docs/api/rest/relations Mô tả: Quản lý các liên kết (connect, disconnect, set) thông qua API.
• Database Transactions: https://docs.strapi.io/dev-docs/database/transactions Mô tả: Sử dụng strapi.db.transaction() cho các hoạt động nguyên tử.
• Database Migrations: https://docs.strapi.io/dev-docs/database/migrations Mô tả: Các scripts di chuyển cấu trúc hoặc dữ liệu (thư mục database/migrations).
• Database Configuration: https://docs.strapi.io/dev-docs/configurations/database Mô tả: Cấu hình config/database.ts (SQLite, PostgreSQL, MySQL).

4. API bên ngoài (REST, GraphQL, Client)

• Content API Overview: https://docs.strapi.io/dev-docs/api/content-api Mô tả: Tổng quan về các API bên ngoài của Strapi.
• REST API Reference: https://docs.strapi.io/dev-docs/api/rest Mô tả: Danh mục chính của các endpoints. Cấu trúc phản hồi phẳng của v5.
• REST API Parameters: https://docs.strapi.io/dev-docs/api/rest/parameters Mô tả: Danh sách đầy đủ các tham số REST API.
• REST API Guides: https://docs.strapi.io/dev-docs/api/rest/guides Mô tả: Các tình huống sử dụng REST API cụ thể.
• REST API Populate & Select: https://docs.strapi.io/dev-docs/api/rest/populate-select Mô tả: Các tham số populate và fields trong các yêu cầu REST.
• REST API Sort & Pagination: https://docs.strapi.io/dev-docs/api/rest/sort-pagination Mô tả: Sắp xếp và phân trang theo offset và page.
• REST API Status: https://docs.strapi.io/dev-docs/api/rest/status Mô tả: Lọc các phản hồi REST theo trạng thái (published/draft).
• REST API Locale: https://docs.strapi.io/dev-docs/api/rest/locale Mô tả: Các yêu cầu REST API với tham số locale.
• REST API Upload: https://docs.strapi.io/dev-docs/api/rest/upload Mô tả: Tải lên các file thông qua POST /api/upload.
• Interactive Query Builder: https://docs.strapi.io/dev-docs/api/rest/interactive-query-builder Mô tả: Sử dụng thư viện qs để xây dựng các URL phức tạp.
• GraphQL API: https://docs.strapi.io/dev-docs/api/graphql Mô tả: Sử dụng các mutations và queries của GraphQL, bộ lọc.
• GraphQL Plugin Config: https://docs.strapi.io/dev-docs/plugins/graphql Mô tả: Cấu hình Apollo Server, Shadow CRUD và giới hạn độ phức tạp trong config/plugins.ts.
• Strapi Client: https://docs.strapi.io/dev-docs/strapi-client Mô tả: Thư viện chính thức @strapi/client cho frontend.
• OpenAPI & Swagger: https://docs.strapi.io/dev-docs/api/openapi Mô tả: Tạo đặc tả OpenAPI, plugin Documentation.

5. TypeScript

• TypeScript Setup & Overview: https://docs.strapi.io/dev-docs/typescript Mô tả: Sử dụng TypeScript trong Strapi.
• TypeScript Development: https://docs.strapi.io/dev-docs/typescript/development Mô tả: Auto-complete, định kiểu cho instance strapi.
• Manipulating Documents: https://docs.strapi.io/dev-docs/typescript/manipulating-documents Mô tả: Sử dụng UID.ContentType và Data.Document để định kiểu nghiêm ngặt.
• TypeScript Configuration: https://docs.strapi.io/dev-docs/typescript/configuration Mô tả: Các cài đặt trong config/typescript.ts và tự động tạo types.
• Adding TypeScript: https://docs.strapi.io/dev-docs/typescript/migration Mô tả: Cách thêm TS vào một dự án JS hiện có.

6. Cấu hình và Tự động hóa (Settings)

• Configurations Overview: https://docs.strapi.io/dev-docs/configurations Mô tả: Tổng quan về thư mục /config.
• Server Config: https://docs.strapi.io/dev-docs/configurations/server Mô tả: config/server.ts (host, port, url, proxy).
• API Config: https://docs.strapi.io/dev-docs/configurations/api Mô tả: config/api.ts (prefixes, giới hạn phân trang).
• Middlewares Config: https://docs.strapi.io/dev-docs/configurations/middlewares Mô tả: Cấu hình các middlewares tích hợp (CORS, security, body) trong config/middlewares.ts.
• Plugins Config: https://docs.strapi.io/dev-docs/configurations/plugins Mô tả: Kết nối và cấu hình các plugins cục bộ (config/plugins.ts).
• Environment Variables: https://docs.strapi.io/dev-docs/configurations/environment Mô tả: Làm việc với .env và helper env().
• CRON Jobs: https://docs.strapi.io/dev-docs/configurations/cron Mô tả: Thực hiện các tác vụ nền theo lịch trình (node-schedule).
• Webhooks: https://docs.strapi.io/dev-docs/configurations/webhooks Mô tả: Cấu hình các triggers cho yêu cầu HTTP đến các hệ thống bên ngoài.
• Features (Feature Flags): https://docs.strapi.io/dev-docs/configurations/features Mô tả: Bật các chức năng thử nghiệm.

7. Plugins và Mở rộng

• Installing Plugins: https://docs.strapi.io/user-docs/plugins Mô tả: Sử dụng Marketplace và CLI để cài đặt plugins.
• Users & Permissions: https://docs.strapi.io/dev-docs/plugins/users-permissions Mô tả: Quản lý người dùng, JWT, ACL, đăng ký và vai trò.
• Upload files / Media Library: https://docs.strapi.io/dev-docs/plugins/upload Mô tả: Cấu hình các nhà cung cấp tải lên file (AWS S3, Local).
• Email Plugin: https://docs.strapi.io/dev-docs/plugins/email Mô tả: Gửi email giao dịch, cấu hình các nhà cung cấp SMTP.
• Custom Fields: https://docs.strapi.io/dev-docs/custom-fields Mô tả: Tạo và đăng ký các kiểu trường tùy chỉnh.
• Sentry Plugin: https://docs.strapi.io/dev-docs/plugins/sentry Mô tả: Tích hợp với Sentry để theo dõi lỗi.

8. Di chuyển v4 -> v5

• Upgrading Introduction: https://docs.strapi.io/dev-docs/migration/v4-to-v5 Mô tả: Tổng quan về quá trình cập nhật lên Strapi 5.
• Step-by-step Guide: https://docs.strapi.io/dev-docs/migration/v4-to-v5/step-by-step Mô tả: Hướng dẫn nâng cấp từng bước.
• Upgrade Tool: https://docs.strapi.io/dev-docs/migration/v4-to-v5/upgrade-tool Mô tả: Sử dụng công cụ CLI (codemods) để di chuyển tự động.
• Breaking Changes: https://docs.strapi.io/dev-docs/migration/v4-to-v5/breaking-changes Mô tả: Danh sách đầy đủ các thay đổi gây phá vỡ (breaking changes).
• Entity Service to Document Service: https://docs.strapi.io/dev-docs/migration/v4-to-v5/entity-service Mô tả: Refactoring các yêu cầu cũ sang API mới và documentId.
• Plugins Migration: https://docs.strapi.io/dev-docs/migration/v4-to-v5/plugins Mô tả: Cập nhật các plugins và sử dụng Plugin SDK.
• Helper-plugin Migration: https://docs.strapi.io/dev-docs/migration/v4-to-v5/helper-plugin Mô tả: Thay thế @strapi/helper-plugin đã bị xóa.
• Design System Updates: https://docs.strapi.io/dev-docs/migration/v4-to-v5/design-system Mô tả: Các thay đổi trong UI components (Design System v2).

9. Hạ tầng và CLI

• Installation & Quick Start: https://docs.strapi.io/dev-docs/installation Mô tả: Cài đặt Strapi (CLI, Docker).
• Command Line Interface (CLI): https://docs.strapi.io/dev-docs/cli Mô tả: Các lệnh strapi generate, build, ts:generate-types.
• Templates: https://docs.strapi.io/dev-docs/templates Mô tả: Tạo các dự án dựa trên các mẫu có sẵn của GitHub.
• Deployment: https://docs.strapi.io/dev-docs/deployment Mô tả: Các yêu cầu đối với máy chủ, các biến cho môi trường production.
• Data Management: https://docs.strapi.io/dev-docs/data-management Mô tả: Import/Export/Transfer dữ liệu giữa các cơ sở dữ liệu (CLI).
• Testing: https://docs.strapi.io/dev-docs/testing Mô tả: Cấu hình Jest và Supertest cho các bài kiểm tra unit và kiểm tra tích hợp.

10. CMS Features và Admin Panel

• Admin Panel Settings: https://docs.strapi.io/user-docs/intro Mô tả: Tổng quan về giao diện đồ họa quản trị.
• Admin Panel Configuration: https://docs.strapi.io/dev-docs/configurations/admin-panel Mô tả: Cấu hình config/admin.ts (secrets, bản dịch).
• Homepage Customization: https://docs.strapi.io/dev-docs/admin-panel-customization/homepage Mô tả: Thêm các widgets vào trang chủ của trang quản trị.
• Content-Type Builder: https://docs.strapi.io/user-docs/content-type-builder Mô tả: Sử dụng GUI để tạo các mô hình dữ liệu.
• Content Manager: https://docs.strapi.io/user-docs/content-manager Mô tả: Giao diện chỉnh sửa các bản ghi.
• Draft & Publish (CMS): https://docs.strapi.io/user-docs/draft-and-publish Mô tả: Cơ chế của các trạng thái nội dung.
• Internationalization (CMS): https://docs.strapi.io/dev-docs/plugins/i18n Mô tả: Dịch nội dung sang các ngôn ngữ khác nhau trong trang quản trị.
• Preview: https://docs.strapi.io/dev-docs/plugins/preview Mô tả: Cấu hình Live Preview (xem trước nội dung trên frontend).
• API Tokens: https://docs.strapi.io/user-docs/api-tokens Mô tả: Các tokens cho tích hợp Server-to-Server.
• Role-Based Access Control (RBAC): https://docs.strapi.io/user-docs/users-roles-permissions Mô tả: Cài đặt quyền cho các quản trị viên panel.
• Single Sign-On (SSO): https://docs.strapi.io/dev-docs/configurations/sso Mô tả: Xác thực quản trị viên thông qua Azure, Google (Enterprise).
• Audit Logs: https://docs.strapi.io/user-docs/audit-logs Mô tả: Nhật ký ghi lại các hành động của quản trị viên (Enterprise).
• Review Workflows: https://docs.strapi.io/user-docs/review-workflows Mô tả: Cấu hình các giai đoạn review nội dung (Enterprise).
• Content History: https://docs.strapi.io/user-docs/content-history Mô tả: Quản lý phiên bản và hoàn tác các thay đổi nội dung (Enterprise).
• Releases: https://docs.strapi.io/user-docs/releases Mô tả: Xuất bản nội dung hàng loạt (Growth/Enterprise).