# Zalo Taxi Backend V5 — Nâng cấp từ V4

## Điểm mới chính

- Branding động: tên app, tagline, màu chủ đạo, logo upload từ Admin.
- Banner theo 6 vị trí: `LOGIN_HERO`, `HOME_TOP`, `HOME_MIDDLE`, `RIDES_TOP`, `PROFILE_TOP`, `ADMIN_TOP`.
- Ảnh minh chứng chuyến riêng tư theo mốc: nhận chuyến, đến điểm đón, hoàn thành, khách hủy và ảnh khác.
- Có thể bắt buộc ảnh sau khi nhận chuyến và trước khi hoàn thành bằng Settings.
- Admin Web + Admin trong Mini App dùng chung API media và ảnh minh chứng.
- Dashboard có thống kê ảnh minh chứng trong ngày và số banner đang bật.

## Cách nâng cấp database V4 -> V5

1. Backup database hiện tại.
2. Import file `database/migrations/upgrade_v5.sql` đúng database đang chạy V4.
3. Không cần import lại toàn bộ `database/schema.sql` nếu hệ thống đã có dữ liệu V4.

Migration V5 chỉ thêm bảng/cấu hình mới, không xóa bảng hoặc dữ liệu V4.

## Thư mục cần quyền ghi

Backend tự tạo thư mục con khi upload, nhưng user chạy PHP cần có quyền ghi vào:

- `storage/private/` — ảnh minh chứng chuyến/hoa hồng, không public trực tiếp.
- `public/uploads/` — logo và banner công khai.

Có thể cấu hình bằng `.env`:

```env
PRIVATE_UPLOAD_DIR=/duong-dan/backend/storage/private
PUBLIC_UPLOAD_DIR=/duong-dan/backend/public/uploads
UPLOAD_MAX_BYTES=5242880
```

## API mới V5

- `GET /api/app/config` — branding + banner + quy định ảnh.
- `POST /api/rides/{id}/proof` — upload ảnh minh chứng chuyến.
- `GET /api/private-media/ride-proof/{id}` — xem ảnh có kiểm tra quyền.
- `GET /api/admin/media`
- `POST /api/admin/media`
- `PUT /api/admin/media/{id}`
- `POST /api/admin/media/{id}/image`
- `DELETE /api/admin/media/{id}`
- `POST /api/admin/branding/logo`

## Cài đặt mới trong Admin > Settings

- `branding.app_name`
- `branding.tagline`
- `branding.primary_color`
- `branding.zalo_login_title`
- `branding.zalo_login_subtitle`
- `ride.accept_photo_required` = `1`/`0`
- `ride.complete_photo_required` = `1`/`0`

`branding.logo_path` được cập nhật tự động khi dùng nút Upload logo.

## Quy trình ảnh minh chứng V5

1. Tài xế nhận chuyến.
2. Nếu `ride.accept_photo_required=1`, tài xế phải upload ảnh `ACCEPTED` trước khi bấm “Đã liên hệ khách”.
3. Khi đến điểm đón có thể upload thêm ảnh `ARRIVED` để đối soát.
4. Trong trạng thái đang chạy, nếu `ride.complete_photo_required=1`, phải upload ảnh `COMPLETED` trước khi bấm “Hoàn thành chuyến”.
5. Người đăng, tài xế của chuyến và Admin được xem ảnh; người khác không được truy cập file riêng tư.

## Sau khi upload code

- Giữ lại `.env` đang dùng của V4 và bổ sung biến mới nếu cần.
- Kiểm tra `APP_URL` đúng domain backend.
- Document root nên trỏ vào thư mục `public/`.
- Mở `/api/health` và `/api/app/config` để kiểm tra.
- Vào `/admin/` > **Logo & banner** để upload logo/banner đầu tiên.