# RULES.md — Quy tắc tiếp tục phát triển website

> **Đọc file này TRƯỚC khi sửa/thêm bất kỳ file nào trong dự án.**
> Đây là website demo cho dịch vụ **Xe hợp đồng - Taxi Cần Thơ**, xây bằng PHP thuần
> (không framework), không cần build step. Có thể chạy ngay bằng `php -S localhost:8000`.

---

## 1. Tổng quan cấu trúc

```
xe-hop-dong-can-tho/
├── index.php                  # Trang chủ
├── 404.php                    # Trang lỗi 404
├── RULES.md                   # <- Bạn đang đọc file này
├── README.md                  # Hướng dẫn chạy thử nhanh
├── config/
│   └── settings.php           # NGUỒN DUY NHẤT: SĐT, Zalo, nav menu, danh sách dịch vụ
├── includes/
│   ├── header.php             # <head>, nav — include ở ĐẦU mọi trang
│   ├── footer.php             # Footer + nút nổi + </body> — include ở CUỐI mọi trang
│   ├── floating-buttons.php   # Nút gọi điện + Zalo nổi (code gốc do người dùng cung cấp)
│   └── icon-*.svg.php         # Các icon SVG nhỏ dùng cho service card
├── assets/
│   ├── css/style.css          # TOÀN BỘ style của site — không viết CSS rời ở nơi khác
│   ├── js/main.js             # JS thuần, không framework
│   └── img/                   # Ảnh thật sẽ để ở đây (hiện đang trống — dùng emoji/SVG demo)
└── pages/
    ├── dich-vu.php                 # Danh sách dịch vụ
    ├── dich-vu-noi-thanh.php       # Chi tiết dịch vụ #1 (TEMPLATE CHUẨN — đọc trước)
    ├── dich-vu-lien-tinh.php       # Chi tiết dịch vụ #2
    ├── dich-vu-san-bay.php         # Chi tiết dịch vụ #3
    ├── bang-gia.php                # Bảng giá
    ├── gioi-thieu.php              # Giới thiệu
    └── lien-he.php                 # Liên hệ (form demo, CHƯA nối backend)
```

## 2. Nguyên tắc bắt buộc

1. **Một nguồn sự thật duy nhất cho thông tin liên hệ**: số điện thoại, Zalo, email,
   địa chỉ, giờ làm việc chỉ được khai báo trong `config/settings.php` (mảng
   `$settings_db`). KHÔNG hard-code số điện thoại/Zalo ở bất kỳ file `.php` nào khác —
   luôn in ra bằng `$settings_db['phone']`, `$settings_db['zalo']`, v.v.
2. **Một nguồn sự thật cho danh sách dịch vụ**: mảng `$services_db` trong
   `config/settings.php`. Trang chủ, trang `/pages/dich-vu.php`, và footer đều loop
   qua mảng này — thêm 1 dịch vụ mới ở đây là đủ để nó xuất hiện khắp nơi.
3. **CSS chỉ ở `assets/css/style.css`**, dùng CSS variables khai báo trong `:root`.
   Không thêm `<style>` inline trừ style 1 lần rất nhỏ (vd: `style="margin-top:14px"`
   đã dùng ở vài chỗ cho spacing cục bộ — chấp nhận được, nhưng màu sắc/font luôn
   phải qua biến CSS).
4. **Mọi trang đều theo khuôn header/footer**: bắt đầu bằng khai báo
   `$base_path`, `$active_nav`, `$page_title`, `$page_desc` rồi `require` header,
   kết thúc bằng `require` footer. Xem mục 3 bên dưới cho khuôn mẫu chính xác.
5. **Nội dung DEMO phải được đánh dấu rõ**: mọi text/giá/số liệu chưa phải dữ liệu
   thật được ghi chú bằng `[DEMO]`, `(demo)`, hoặc `<em>[DEMO — ...]</em>`. Khi thay
   bằng nội dung thật, XÓA các nhãn demo này.
6. **Không tự ý đổi cấu trúc của `includes/floating-buttons.php`** (nút gọi/Zalo nổi)
   — đây là code gốc người dùng cung cấp. Nếu cần đổi số điện thoại/Zalo, sửa trong
   `config/settings.php`, không sửa trực tiếp file này.

## 3. Khuôn mẫu bắt buộc cho MỌI trang mới

### Trang ở thư mục gốc (ngang hàng `index.php`)
```php
<?php
$base_path  = '';
$active_nav = 'Tên mục trong nav_menu, để trống nếu không match';
$page_title = 'Tiêu đề trang | ' . ($settings_db['site_name'] ?? '');
$page_desc  = 'Mô tả 1-2 câu cho SEO';
require __DIR__ . '/includes/header.php';
?>
... nội dung HTML ...
<?php require __DIR__ . '/includes/footer.php'; ?>
```

### Trang trong `/pages/`
Giống hệt trên nhưng:
- `$base_path = '..';`
- `require __DIR__ . '/../includes/header.php';`
- `require __DIR__ . '/../includes/footer.php';`

**Luôn dùng `$base_path` khi trỏ tới CSS/ảnh/link nội bộ** (`<?= $base_path ?>/assets/...`,
`<?= $base_path ?>/index.php`...) để link không gãy dù file nằm ở cấp thư mục nào.

## 4. Thêm một trang dịch vụ chi tiết mới

1. Copy `pages/dich-vu-noi-thanh.php` → `pages/dich-vu-[slug-moi].php`.
2. Sửa `$page_title`, breadcrumb, nội dung hero/checklist/bảng giá.
3. Trong `config/settings.php`, mở mảng `$services_db`, sửa `detail_url` của dịch vụ
   tương ứng (hoặc thêm phần tử mới nếu là dịch vụ hoàn toàn mới) trỏ tới file vừa tạo.
4. Nếu dịch vụ mới cần icon riêng, thêm file `includes/icon-[ten].svg.php` (SVG 24x24,
   dùng `stroke="currentColor"` để ăn theo màu `--color-primary`), rồi set
   `'icon' => 'ten'` trong `$services_db`.

## 5. Design tokens (đã áp dụng trong `assets/css/style.css`)

- **Chủ đề**: "Bến sông Cần Thơ" — teal sông nước làm màu chính, vàng xoài chín làm
  điểm nhấn, cam san hô cho nút hành động (CTA), tránh các tông màu mặc định
  kem/terracotta hay nền tối kiểu "AI generic" thường gặp.
- **Màu**: xem biến `--color-*` trong `:root` của `style.css` — sửa màu ở đó, không
  viết mã hex mới rải rác trong file khác.
- **Font**: `Baloo 2` (tiêu đề, bo tròn hiện đại) + `Be Vietnam Pro` (nội dung, hỗ trợ
  tiếng Việt tốt) + `JetBrains Mono` (giá tiền, số liệu, mã dịch vụ).
- **Signature element**: đường "tuyến xe" SVG dashed chạy animation trong hero
  (`.route-path`), tượng trưng cho các cung đường/tuyến sông của Cần Thơ — tái sử
  dụng motif "điểm dừng" (route-dot) nếu cần cho các khối khác, đừng tạo motif mới
  không liên quan.
- **Số thứ tự** (1/2/3/4) chỉ dùng ở khối "Quy trình đặt xe" vì đó là chuỗi bước thật
  sự có thứ tự — không thêm numbering trang trí ở nơi khác.

## 6. Việc CHƯA làm (đánh dấu TODO rõ ràng cho lần sau)

- [ ] Thay toàn bộ nội dung `[DEMO]` bằng nội dung thật (địa chỉ, giá, mô tả dịch vụ).
- [ ] Thay ảnh minh hoạ (hiện dùng icon SVG/emoji) bằng ảnh xe/ tài xế thật trong
      `assets/img/`.
- [ ] Nối form ở `pages/lien-he.php` với backend thật (gửi email/lưu DB) — hiện chỉ
      `alert()` demo qua `onsubmit`.
- [ ] Nhúng Google Maps thật (`$settings_db['map_embed']`) ở trang liên hệ.
- [ ] Thêm sitemap.xml / robots.txt khi có domain thật.
- [ ] Rà lại SĐT/Zalo là số thật trước khi đưa vào production (hiện là
      `0389 765 765` theo yêu cầu người dùng — ĐÃ đúng theo yêu cầu, không phải demo).

## 7. Kiểm tra nhanh trước khi bàn giao

- [ ] Không còn số điện thoại/Zalo nào hard-code ngoài `config/settings.php`.
- [ ] Mọi trang mới đều có nút gọi + Zalo nổi hoạt động (tự động có nếu include đúng
      `includes/footer.php`).
- [ ] Site chạy được bằng `php -S localhost:8000` từ thư mục gốc dự án.
- [ ] Nội dung demo được đánh dấu rõ, không bị hiểu nhầm là thông tin thật.
