Diepxuan Portal (Laravel 11)

Portal là ứng dụng web cốt lõi cho hệ sinh thái Diepxuan, được xây dựng trên nền tảng Laravel 11. Nó đóng vai trò là nền tảng tập trung tích hợp nhiều module nghiệp vụ khác nhau thông qua kiến trúc module hóa.

Tài liệu quan trọng

Documentation Index

• Documentation Hub: Index toàn bộ tài liệu dự án

Bắt buộc đọc (AI Agents & Developers)

• Hướng dẫn AI Agent: BẮT BUỘC. Quy tắc nghiêm ngặt cho AI agents về phạm vi công việc, Git workflow và an toàn code
• Tổng quan kiến trúc: Kiến trúc hệ thống, luồng dữ liệu, thành phần cốt lõi
• Hệ thống Package: 14 package nội bộ trong diepxuan/ và cách module hoạt động
• Thiết lập môi trường: Hướng dẫn setup development environment

Project Documentation (trong docs/)

• Workspace Guide: Cấu trúc thư mục, quy tắc tạo file, Git workflow
• Core Package Loading: Auto-discovery và auto-registration system
• Package Namespace Conventions: Quy ước namespace cho packages
• Serve:Dev Commands: Development server commands
• Model Architecture: Kiến trúc Model 3 lớp

Core Identity (OpenClaw)

• SOUL.md: Core operating identity
• IDENTITY.md: Role definition & capabilities
• AGENTS.md: Workspace operating protocol
• USER.md: User profile

---

Bắt đầu nhanh

1. Clone & Cài đặt

git clone git@github.com:diepxuan/portal.git
cd portal
composer install
npm install
cp .env.example .env
php artisan key:generate

2. Cấu hình Database

Cập nhật file .env với thông tin kết nối database.

3. Chạy Dev Server

Option 1: Portal-dev.sh wrapper (Recommended)

./portal-dev.sh start      # Start development
./portal-dev.sh status     # Check status
./portal-dev.sh stop       # Stop everything

Option 2: Artisan commands

php artisan serve:dev          # Start Laravel + Vite
php artisan serve:dev:status   # Check status
php artisan serve:dev:stop     # Stop servers

Xem chi tiết: Serve:Dev Commands Documentation

---

Cấu trúc dự án

portal/
├── Core Identity (OpenClaw)
│   ├── SOUL.md, IDENTITY.md, AGENTS.md, USER.md
│   └── BOOTSTRAP.md, MEMORY.md, HEARTBEAT.md
│
├── Documentation
│   ├── README.md, AI_AGENT_GUIDE.md, ARCHITECTURE.md
│   ├── DEVELOPMENT.md, PACKAGES.md
│   └── docs/                    # Project & package docs
│       ├── README.md            # Documentation index
│       ├── project/             # Project-wide docs
│       └── packages/            # Package-specific docs
│
├── Laravel Application
│   ├── app/                     # Standard Laravel app
│   ├── diepxuan/                # CORE BUSINESS PACKAGES (14 packages)
│   ├── config/, database/, resources/, routes/, tests/
│   └── ...
│
└── Scripts & Config
    ├── portal-dev.sh            # Development wrapper
    ├── composer.json, package.json
    └── .env, .gitignore

Thư mục quan trọng

Thư mục	Mô tả
diepxuan/	Core Business Logic - 14 modular packages (symlink qua Composer). Hầu hết development diễn ra ở đây
app/	Standard Laravel application logic
docs/	Documentation hub - project và package docs
config/	Configuration files
database/	Migrations, seeders, factories
resources/	Views, assets, lang files

---

Packages (diepxuan/)

14 core business packages:

Package	Mô tả	README
laravel-core	Core system: package management, auto-discovery	README
laravel-catalog	Catalog management, main business package	README
laravel-simba	Accounting integration	README
laravel-support	Developer utilities & commands	README
laravel-magento	Magento API integration	README
laravel-ronaldjack	Ronald Jack SDK	README
laravel-log	Custom logging channels	README
laravel-disreg	Disable user registration	README
laravel-gmail	Gmail API client	README
laravel-scavenger	Web scraper engine	README
laravel-currency	Currency formatting	README
laravel-eloquent-composite	Composite model support	README
php-charset	Vietnamese charset conversion	README

Xem tổng quan: PACKAGES.md

---

Đóng góp (Contributing)

Git Workflow

1. Mỗi task = 1 branch mới
2. Mỗi set thay đổi = 1 PR mới
3. Luôn commit cho mọi thay đổi
4. Không làm việc trực tiếp trên main

Cấm tuyệt đối

• Tự ý push
• Tự ý tạo PR
• Tự ý merge/revert
• Cập nhật PR cũ
• Force push

Chỉ push khi Sếp nói: "Em tạo PR đi"

Xem chi tiết: AI_AGENT_GUIDE.md §3

---

Development Tools

Commands hữu ích

# Development server
php artisan serve:dev
php artisan serve:dev:status
php artisan serve:dev:stop

# Health check
php artisan serve:dev:health --fix

# Clear cache
php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear

# View logs
php artisan serve:dev:logs --follow

Code Quality

# Format code
./vendor/bin/pint

# Run tests
php artisan test

---

Checklist cho AI Agents

Trước khi bắt đầu task:

• Đọc SOUL.md - Core identity
• Đọc USER.md - User profile
• Đọc AI_AGENT_GUIDE.md - BẮT BUỘC
• Xác nhận phạm vi: Chỉ diepxuan/ packages
• Tạo branch mới: task/<tên-task>
• Commit với message: <package>: mô tả
• Chờ Sếp review trước khi push

---

Links

• Repository: https://github.com/diepxuan/portal
• Documentation: docs/README.md
• Community: https://discord.com/invite/clawd

---

Laravel 11 | PHP 8.2+ | Livewire 3 | Tailwind CSS