| name | pagify-module-core |
| description | Phát triển tính năng, sửa lỗi, refactor và review cho module core của Pagify (Laravel 12 + Inertia Vue). ùng khi làm auth admin, role-permission, admin groups, admins, tokens, plugin/theme management, audit logs, frontend fallback, và governance. |
| argument-hint | Mục tiêu thay đổi ở core module là gì? (feature, bugfix, refactor, security, test) |
| user-invocable | true |
Pagify Core Development Workflow
Mục Tiêu
Skill này chuẩn hóa quy trình làm việc với module core để:
- Triển khai feature mới đúng kiến trúc module
- Sửa lỗi không gây hồi quy
- Refactor an toàn và dễ bảo trì
- Đảm bảo test coverage và tiêu chí hoàn tất
Khi Nào Sử Dụng
Sử dụng skill này khi thay đổi trong phạm vi modules/core và các điểm tích hợp liên quan:
- Admin auth, session, forgot/reset password
- Dashboard và settings pages (admin)
- Permission, admin groups, admins, API tokens
- Plugin/theme management endpoints
- Audit logs, access governance
- Frontend fallback routing, theme asset serving
Inputs Cần Có
- Loại thay đổi:
feature, bugfix, refactor, security, test-only
- Impact scope: API, admin UI, auth/permission, plugin/theme, fallback routing
- Mục tiêu nghiệp vụ và expected behavior
- Ràng buộc backward compatibility (nếu có)
Quy Trình Thực Thi
- Xác định phạm vi và rủi ro
- Xác định route/API/chức năng bị ảnh hưởng trong core.
- Đánh dấu mức độ rủi ro:
high nếu đóng vào auth, permission, token, middleware, fallback routing.
- Liệt kê behavioral contract cần giữ nguyên.
- Kiểm tra tài liệu và code map
- Đọc tài liệu module core trước, sau đó map tới code thực tế trong
modules/core.
- Xác định đúng điểm sửa: route, controller, service, repository, policy, request, resource.
- Không đặt business logic trong controller.
- Thiết kế thay đổi theo kiến trúc
- Đưa logic nghiệp vụ vào
src/Services theo SRP.
- Tách logic truy cập dữ liệu vào
src/Repositories.
- Dùng dependency injection; tránh facade trừ
config, log, auth.
- Đặt typed properties và return types theo PHP 8.2 + PSR-12.
- Nhánh quyết định theo loại thay đổi
- Nếu là
feature:
- Định nghĩa API contract và validation trước.
- Thêm service/repository trước controller.
- Cập nhật policy/permission nếu cần.
- Nếu là
bugfix:
- Tái tạo bug bằng test (ưu tiên) hoặc ghi rõ steps tái tạo.
- Sửa tối thiểu để giải quyết root cause, tránh scope creep.
- Nếu là
security:
- Kiểm tra authz/authn, token scope, input validation, audit log.
- Đánh giá tác động denial paths và escalation paths.
- Nếu là
refactor:
- Giữ nguyên public behavior, bổ sung regression tests.
- Admin UI và public integration (nếu có)
- Nếu có admin page:
- Theo convention Inertia + Vue 3 + Tailwind trong
themes/admin/{theme_name}.
- Dùng Composition API,
<script setup lang="ts">, typed props/emits.
- Form sử dụng Inertia form helper + server-side validation qua FormRequest.
- Nếu ảnh hưởng public site:
- Xử lý data ở backend, truyền dữ liệu đã xử lý sang Twig templates.
- Test và xác minh
- Thêm hoặc cập nhật tests trong
modules/core/tests/Feature và modules/core/tests/Unit.
- Ưu tiên test cho controller/service/policy mới hoặc bị sửa.
- Chạy test liên quan theo scope thay đổi.
- Xác minh các luồng quan trọng của core:
- access management
- admin end-to-end flow
- plugin/theme management behavior
- profile flow
- frontend fallback va theme sandbox hardening
- Hoàn tất và báo cáo
- Viết tóm tắt thay đổi: nguyên nhân, giải pháp, phạm vi ảnh hưởng.
- Liệt kê rủi ro còn lại và cách rollback (nếu cần).
- Đảm bảo migration/config docs được cập nhật khi có thay đổi liên quan.
Tiêu Chí Hoàn Tất
- Kiến trúc đúng convention module + SRP service/repository
- Không đưa business logic vào controller
- Validation/authz/policy được cập nhật đầy đủ theo scope
- Test mới đã có và test liên quan pass
- Không phá vỡ route/API contract hiện có (trừ khi được yêu cầu)
- Có ghi chú rủi ro và hướng verify sau khi merge
Tài Liệu Tham Khảo
- Core module docs:
docs/docs/modules/core-module.md
- Workspace conventions:
.github/instructions/copilot.instructions.md
Mẫu Prompt Gọi Skill
/pagify-core Sửa lỗi 403 sai permission khi cập nhật admin group, tạo test tái tạo bug trước khi fix./pagify-core Thêm endpoint quản lý API token cho admin, gồm service/repository, policy và feature tests./pagify-core Refactor plugin management controller để đưa business logic vào service, giữ nguyên API contract.
