Source Code Adscampaign PHP – Quản lý QC đa sàn ROI

## Giới thiệu chung

**Adscampaign (UpS)** là hệ thống quản trị vận hành quảng cáo đa sàn kết hợp quản lý đơn hàng và tồn kho, viết bằng **PHP MVC thuần** (không Laravel/Composer), dùng **MySQL** và giao diện tiếng Việt.

Mục đích: giúp SME / shop e-commerce theo dõi hiệu suất chiến dịch (chi phí, doanh thu, đơn, ROI), tự động hóa điều chỉnh ngân sách–ROI, và đồng bộ vận hành bán hàng theo SKU trên TikTok, Facebook, Shopee.

**Đối tượng sử dụng:** team performance marketing, vận hành shop, lập trình viên học PHP MVC, sinh viên làm đồ án / share code hệ thống ads + ops.

> Lưu ý từ source: hiện **không có đăng nhập/phân quyền**; toàn bộ là panel vận hành nội bộ (một giao diện). Phần dưới tách theo nhóm tính năng để dễ đối chiếu khi bán/share code.

---

## Các tính năng nổi bật

### Người dùng vận hành (Client / Ops)

- **Dashboard chiến dịch:** lọc theo sàn, xem chi phí – doanh thu – đơn – ROI theo ngày/giờ (Chart.js).

- **Loại chiến dịch:** Product GMV Max, Live GMV Max.

- **Kênh hỗ trợ:** TikTok, Facebook, Shopee.

- **Điều khiển nhanh:** bật/tắt chiến dịch, chỉnh ngân sách & ROI mục tiêu.

- **Lịch sử đồng bộ:** theo dõi sync history chiến dịch.

- **Đơn hàng đa sàn:** tạo/xem/sửa/xóa; trạng thái `pending → processing → shipped → completed/cancelled`.

- **Tồn kho SKU:** xem tồn, điều chỉnh thủ công; hoàn/trừ tồn theo trạng thái đơn.

- **Sản phẩm mẫu trong DB:** mỹ phẩm (kem chống nắng, serum, son kem lì) kèm giá VND.

### Quản trị quy tắc & cấu hình (Admin / Automation)

- **Auto Rule:** tạo, sửa, xóa, sao chép quy tắc tự động.

- **Điều kiện metric:** chi phí, ROI mục tiêu, ROI thực tế, ngân sách ngày.

- **Hành động:** tăng/giảm budget, chỉnh ROAS/ROI, set status chiến dịch (theo lịch hoặc điều kiện).

- **Lịch sử thực thi quy tắc:** theo dõi execution history & kết quả chạy rule.

- **API nội bộ:** dashboard campaigns, CRUD orders/inventory/rules qua các endpoint `/api/...`.

- **Menu dự kiến (placeholder):** Trang chủ, Tích hợp, Cài đặt, Sản phẩm, Khuyến mãi, Khách hàng (chưa implement đầy đủ).

---

## Công nghệ & Cơ sở dữ liệu

| Thành phần | Chi tiết |

|---|---|

| Backend | PHP 8.x, namespace `App\`, `declare(strict_types=1)` |

| Kiến trúc | MVC tự viết: Router, Controller, Service, Model, View |

| Frontend | HTML/CSS/JS vanilla, Font Awesome 6, Google Fonts Inter |

| Biểu đồ | Chart.js (CDN) |

| Database | MySQL 8, PDO, DB name `ads_campaign` |

| Server | Apache + mod_rewrite (Laragon), `.htaccess` → `index.php` |

| Cấu hình | `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS` |

**Bảng chính:** `campaign`, `report_daily`, `report_hourly`, `sync_history`, `auto_config_rule`, `auto_config_group*`, `auto_execution_history`, `product`, `inventory_stock`, `sales_order`, `sales_order_item`.

**Không dùng:** Composer packages, Node/npm, Redis, framework auth, tích hợp API ads thật (UI “Tải chiến dịch” mang tính mock/placeholder).

---

## Cấu trúc thư mục & Cài đặt

### Cấu trúc chính

- `index.php` — front controller  

- `routes/web.php` — định nghĩa route trang & API  

- `app/Core/` — Router, Database, View  

- `app/Controllers/` — Campaign, Rule, Order, Inventory  

- `app/Services/`, `app/Models/`, `app/Views/`  

- `config/database.php` — kết nối MySQL  

- `public/css`, `public/js` — asset tĩnh  

- `ads_campaign.sql`, `database/orders_inventory.sql` — schema/data  

- `setup_database.php`, `db_healthcheck.php` — khởi tạo & kiểm tra DB  

### Cách chạy nhanh (theo code, không có README)

1. Đặt project vào Laragon: `www/adscampaign` (rewrite path `/adscampaign/`).

2. Tạo/cấu hình MySQL DB `ads_campaign` (mặc định `root` / password rỗng).

3. Chạy `php setup_database.php` hoặc import `ads_campaign.sql` (+ `orders_inventory.sql` nếu cần).

4. (Tuỳ chọn) `php migrate_add_created_at.php`, kiểm tra `db_healthcheck.php`.

5. Truy cập: `http://localhost/adscampaign/`.

**Trang chính:** `/` (dashboard QC), `/rule_list`, `/create_rule`, `/rule_execution_history`, `/orders`, `/inventory`, `/ads/history`.