# ĐẶC TẢ TRIỂN KHAI — Chat đa tài khoản Zalo cá nhân trên Laravel thuần (không Node.js)

> **Người đọc chính:** AI coding agent (Claude Code) và lập trình viên Laravel sẽ dựng lại
> hệ thống này trên một codebase Laravel khác.
> **Nguồn:** hệ thống ToolChat/FlyChat đang chạy (Laravel 13 + worker Node dùng `zca-js@2.1.2`),
> toàn bộ tài liệu trong `docs/`, `PROMPT-zalo-internal-chat.md`, schema và route thật của backend.
> **Tầng giao thức Zalo của hệ thống mới:** gói Composer [`eric-sa/zca-php`](https://packagist.org/packages/eric-sa/zca-php)
> (bản PHP của `zca-js@2.2.0`, MIT) — **không** tự viết lại giao thức.
> **Ngày biên soạn:** 02/11/2026. **Cập nhật:** 03/11/2026 — chuyển tầng giao thức từ "port tay
> zca-js" sang dùng `eric-sa/zca-php`.

---

## 0. ĐỌC TRƯỚC KHI CODE

### 0.1 Mục tiêu của tài liệu

Tài liệu này đủ chi tiết để một agent triển khai **từ con số 0** một module "Zalo Inbox" vào một
hệ thống Laravel có sẵn mà **không cần đọc lại mã nguồn hệ thống cũ**. Mỗi mục có:

- **Luồng** (ai gọi ai, theo thứ tự nào).
- **Quy tắc bắt buộc** — các quy tắc này đến từ lỗi thật đã gặp ở hệ thống cũ; vi phạm là mất tin,
  gửi nhầm, hoặc lộ dữ liệu.
- **Tiêu chí nghiệm thu** để biết khi nào xong.

Quy ước: **PHẢI** = bắt buộc; **NÊN** = khuyến nghị mạnh, chỉ bỏ khi có lý do ghi rõ;
**KHÔNG ĐƯỢC** = cấm.

### 0.2 Giả định về "không dùng JS khác"

Hệ thống cũ cần một tiến trình Node.js (`worker`) để nói chuyện với Zalo qua thư viện `zca-js`.
Hệ thống mới **thay toàn bộ worker Node bằng PHP**, tầng giao thức dùng gói `eric-sa/zca-php`
(cùng endpoint, tham số, thuật toán mã hoá, tên API và thứ tự đối số với `zca-js`):

| Tầng | Hệ thống cũ | Hệ thống mới (tài liệu này) |
|---|---|---|
| Giao thức Zalo (đăng nhập QR, mã hoá, WebSocket, gửi tin) | Node + `zca-js@2.1.2` (có vá) | **`eric-sa/zca-php`** bọc bởi lớp mỏng `app/Zalo/Protocol` (mục 4) |
| Tiến trình giữ WebSocket | `worker` (Fastify) | `php artisan zalo:gateway` (daemon PHP) |
| Đường tin về DB | worker → HTTP + HMAC → Laravel | gateway → Redis list → `php artisan zalo:consume` → MySQL |
| Giao diện | Blade + Alpine.js + Bootstrap | **Blade + JavaScript thuần (vanilla, không framework, không build step) + CSS thuần** |

Nếu hệ thống đích đã có sẵn Alpine/Bootstrap thì vẫn dùng được, nhưng đặc tả UI ở mục 7 viết
theo JS thuần để không phụ thuộc thư viện nào.

Thư viện Composer được phép (đều là PHP thuần, không phải JS):

| Gói | Dùng cho | Bắt buộc? |
|---|---|---|
| `eric-sa/zca-php` **2.1.0** (ghim đúng bản, xem 9.5) | đăng nhập QR/cookie, mã hoá tham số, gọi HTTP API, listener WebSocket | PHẢI |
| ↳ kéo theo: `react/event-loop` ^1.5, `ratchet/pawl` ^0.4.1, `react/async` ^4.3, `react/promise` ^3.2, `react/promise-timer`, `evenement/evenement` ^3, `guzzlehttp/guzzle` ^7.8, `psr/log` | event loop của gateway, WebSocket client, HTTP đồng bộ | tự có qua zca-php — **không** require riêng |
| `react/http` | **không cần** — zca-php gọi HTTP bằng Guzzle đồng bộ; việc HTTP phát sinh ở gateway đẩy sang consumer/queue (2.4) | không |
| `endroid/qr-code` | **không cần** — Zalo trả sẵn ảnh QR PNG base64 | không |

zca-php yêu cầu PHP ≥ 8.1 (Laravel 13 đã đòi cao hơn). Gói có `Zca\Laravel\ZcaServiceProvider` +
facade, nhưng hệ thống này **không dùng** singleton của nó: mỗi tài khoản cần một `Zca\Zalo`/`Zca\API`
riêng, tạo qua `ZcaFactory` (2.5) để luôn có cùng options.

Extension PHP cần: `json`, `openssl`, `zlib`, `curl`, `mbstring` (zca-php đòi 4 cái `json`/`mbstring`/`openssl`/`zlib`), `pdo_mysql`, `redis` (phpredis),
`gd` hoặc `exif` (đọc kích thước ảnh), `pdo_sqlite` + `sqlite3` (chỉ cho mục đồng bộ tin cũ từ
điện thoại), binary `xz`/`xzcat` trên máy (chỉ cho mục đó).

### 0.3 Cảnh báo phải đọc

1. **Giao thức Zalo cá nhân là giao thức không chính thức**, có được nhờ phân tích ngược (thư viện
   `zca-js`, và bản PHP `zca-php` dùng ở đây — README của gói ghi rõ "chỉ cho học tập/nghiên cứu").
   Dùng nó trái điều khoản của Zalo. Rủi ro khoá tài khoản là có thật và tăng theo số
   tài khoản dùng chung một IP. Zalo đổi giao thức là gãy. Hãy để người ra quyết định kinh doanh
   biết điều này trước khi triển khai.
2. **Lịch sử chat cũ KHÔNG lấy lại được bằng API.** Kho tin nhắn chỉ có những gì hệ thống nhận
   được từ lúc bật listener. Vì vậy `zalo_messages` là **dữ liệu không tái tạo được**: mọi thiết
   kế quanh nó (hàng đợi bền, chống trùng, xoá mềm, đổi chủ dữ liệu khi tạo lại tài khoản) đều
   xuất phát từ điều này. Ngoại lệ duy nhất: luồng "đồng bộ từ điện thoại" (mục 5.17), cần người
   dùng bấm xác nhận trên điện thoại.
3. **Tin gửi đi là thật và không thu hồi được từ phía công cụ** (trừ thao tác "thu hồi" của
   Zalo trong thời hạn cho phép). Mọi chỗ có thể gửi nhầm danh nghĩa/nhầm người đều được đánh dấu
   **[GỬI NHẦM]** trong tài liệu — phải làm đúng từng chữ.
4. **Credential Zalo (cookie + imei + userAgent) = chìa khoá vào tài khoản.** Ai có nó là đăng
   nhập được. PHẢI mã hoá khi lưu, không log, không trả về API.

### 0.4 Thứ tự ưu tiên khi phải đánh đổi (không được đảo)

```
Không mất tin / không gửi nhầm  >  UX mượt  >  tiết kiệm tài nguyên  >  code đơn giản  >  thêm tính năng
```

### 0.5 Quy ước kiến trúc Laravel

- Luồng 3 tầng: **Controller → Service → Repository**.
  - Controller: chỉ nhận Request (FormRequest), gọi Service, trả Response. Không đụng Model.
  - Service: nghiệp vụ. Không gọi `DB::` / query trực tiếp — đi qua Repository.
  - Repository: chỉ Eloquent/Query Builder.
  - Riêng tầng giao thức Zalo nằm ở `app/Zalo/Protocol/*`: lớp bọc mỏng quanh `eric-sa/zca-php`,
    không phụ thuộc Eloquent, để test độc lập. **Chỉ** thư mục này được `use Zca\…`; Service,
    Gateway, Job đi qua interface ở mục 4 — đổi/nâng thư viện chỉ sửa một chỗ, và test mock được.
- Docblock và comment bằng **tiếng Việt có dấu**, comment giải thích **TẠI SAO**.
- Test: **không chạy trên DB thật**. Dùng SQLite in-memory hoặc DB test riêng. Không chạy và
  không đề xuất `migrate:fresh`, `migrate:refresh`, `db:wipe`, `TRUNCATE`, `DROP`.
  Lưu ý: SQLite cho phép subquery trỏ vào chính bảng đang `DELETE`, MySQL cấm (lỗi 1093) — thay
  đổi có SQL thô PHẢI chạy thêm trên MySQL test.

---

## 1. TỔNG QUAN SẢN PHẨM

### 1.1 Bài toán

Doanh nghiệp có nhiều nhân viên trực chat và nhiều tài khoản Zalo **cá nhân** (Zalo Sale 01, 02…).
Họ cần một màn hình web duy nhất để:

- Gom hội thoại của nhiều tài khoản Zalo về một danh sách, đọc và trả lời như Zalo Web.
- Không bỏ sót tin (huy hiệu chưa đọc chính xác, tin không bao giờ mất).
- Phân quyền: nhân viên chỉ thấy tài khoản Zalo được giao.
- Có công cụ tăng tốc: tin mẫu, thẻ phân loại, trả lời trích dẫn, sticker, AI (mở rộng).

### 1.2 Vai trò

| Vai trò | Quyền |
|---|---|
| **Nhân viên (`staff`)** | Màn chat + danh bạ của tài khoản Zalo do mình tạo **hoặc** được giao. Không vào trang quản trị. |
| **Quản trị viên (`admin`)** | Tất cả tài khoản Zalo, trang Tài khoản Zalo, Nhân viên, Thẻ, Tin mẫu, (AI, Chiến dịch nếu có). |

Đăng nhập bằng **số điện thoại + mật khẩu** (nhân viên chưa chắc có email công ty). Không có tự
đăng ký, không có quên mật khẩu qua email — admin tạo tài khoản và đặt lại mật khẩu hộ.
Nếu hệ thống đích đã có auth riêng thì dùng auth đó, chỉ cần giữ hai vai trò trên.

### 1.3 Danh sách tính năng và phase

| # | Tính năng | Phase |
|---|---|---|
| F1 | Quản lý tài khoản Zalo: thêm, mở phiên, quét QR, đóng phiên, đăng nhập lại, xoá | 1 |
| F2 | Gateway giữ WebSocket, nhận tin realtime, ghi MySQL (chống trùng, không mất tin) | 1 |
| F3 | Danh sách hội thoại (đa tài khoản), tìm kiếm, phân trang con trỏ, huy hiệu chưa đọc | 1 |
| F4 | Đọc tin (chữ, ảnh, video, tệp, sticker, danh thiếp, link), phân trang tin cũ | 1 |
| F5 | Gửi chữ, emoji, ảnh/video/tệp (chọn, dán clipboard, kéo-thả), optimistic UI | 1 |
| F6 | Đăng nhập nhân viên + phân quyền theo tài khoản Zalo | 1 |
| F7 | Trả lời trích dẫn, gắn thẻ @ trong nhóm | 2 |
| F8 | Reaction (thả + hiển thị của mọi người), thu hồi, xoá phía tôi, chuyển tiếp | 2 |
| F9 | Danh bạ (bạn bè + nhóm), mở hội thoại từ danh bạ, ảnh đại diện/tên chuẩn | 2 |
| F10 | Hội thoại ẩn (ẩn theo Zalo), đổi tên hiển thị nội bộ, xoá hội thoại | 2 |
| F11 | Kết bạn (tra số điện thoại), lời mời đến, chấp nhận/từ chối, xoá bạn | 3 |
| F12 | Nhóm: tạo, đổi tên/ảnh, thêm/xoá thành viên | 3 |
| F13 | Sticker, gửi danh thiếp, video URL, thẻ ngân hàng | 3 |
| F14 | Thẻ phân loại hội thoại, tin nhắn mẫu `/mã` | 3 |
| F15 | Đồng bộ tin tồn (old messages) qua WebSocket | 2 |
| F16 | Đồng bộ toàn bộ lịch sử từ điện thoại (`pull_mobile_msg`) | 4 (tuỳ chọn) |
| F17 | AI tự trả lời, chiến dịch gửi hàng loạt, Zalo OA | Phụ lục, ngoài phạm vi chính |

---

## 2. KIẾN TRÚC

### 2.1 Nguyên lý

```
Zalo ──WebSocket──► zalo:gateway (PHP daemon) ──RPUSH──► Redis list "zalo:ingest"
                                                              │
                                                    zalo:consume (PHP daemon)
                                                              │  upsert theo lô
                                                              ▼
Người dùng ──► Laravel web (php-fpm) ──đọc──────────────► MySQL  (NGUỒN SỰ THẬT)
           └──► Laravel web ──HTTP mã hoá (gửi tin, tra cứu)──► Zalo
           └──► Laravel web ──RPUSH lệnh──► Redis "zalo:gw:cmd:{shard}" ──► gateway (mở/đóng phiên…)
```

- **MySQL là nguồn sự thật** cho hội thoại và tin nhắn. Giao diện **không bao giờ** hỏi Zalo để
  đọc danh sách hội thoại hay tin nhắn (Zalo không có API "hội thoại gần đây" — sidebar Zalo Web
  được dựng phía client từ dữ liệu nhận qua WebSocket).
- **Gửi tin và tra cứu** (danh bạ, thông tin người dùng/nhóm, sticker…) là lời gọi HTTP thường
  tới Zalo, có mã hoá tham số. Gọi được từ **bất kỳ tiến trình PHP nào** có "ngữ cảnh phiên"
  (cookie, imei, secret key, service map) — không cần đi qua gateway: tiến trình web dựng lại
  `Zca\API` từ `zalo:ctx` mà không đăng nhập lại (4.1).
  **Ngoại lệ:** gửi **video/tệp** (không phải ảnh) PHẢI chạy trong gateway, vì zca-php chỉ coi upload
  xong khi nhận sự kiện `file_done` qua chính WebSocket của phiên đó (5.10).
- **Chỉ có một việc bắt buộc phải là tiến trình sống lâu:** giữ WebSocket để nhận tin. Đó là
  `zalo:gateway`.

### 2.2 Các tiến trình

| Tiến trình | Lệnh | Số bản | Việc |
|---|---|---|---|
| web | php-fpm | theo tải | UI, API JSON cho UI, gửi tin, tra cứu Zalo |
| gateway | `php artisan zalo:gateway --shard=N --shards=M` | M (1 bản / ~100–200 tài khoản) | Đăng nhập lại bằng cookie, giữ WebSocket, giải mã frame, chuẩn hoá tin, đẩy vào Redis; nhận lệnh từ Redis |
| consumer | `php artisan zalo:consume` | 1–2 | Lấy lô từ `zalo:ingest`, ghi MySQL, cập nhật hội thoại, bắn job phụ |
| queue | `php artisan queue:work --queue=zalo-login,default` | 2 | Job đăng nhập QR (chạy lâu tới 5 phút), job tra hồ sơ, job prune, auto-reply |
| scheduler | `php artisan schedule:work` (hoặc cron) | 1 | Đồng bộ hội thoại ẩn, dọn cache, kiểm tra heartbeat gateway |

Mọi daemon chạy dưới supervisor/systemd với `autorestart=true`, `stopwaitsecs=30` (để gateway kịp
xả hàng đợi trong RAM — xem 5.6).

### 2.3 Khoá Redis (bảng tổng)

| Khoá | Kiểu | Ai ghi | Ai đọc | Ý nghĩa |
|---|---|---|---|---|
| `zalo:ingest` | list | gateway (RPUSH) | consumer | Hàng đợi bền các bản ghi tin/sự kiện/trạng thái (JSON) |
| `zalo:ingest:processing` | list | consumer (LMOVE) | consumer | Lô đang xử lý; consumer chết → khởi động lại trả về `zalo:ingest` |
| `zalo:gw:cmd:{shard}` | list | web/queue | gateway | Lệnh cho gateway: `start`, `stop`, `relogin`, `forget`, `request_old_messages`, `send_files` (5.10) |
| `zalo:gw:reply:{requestId}` | list, TTL 300s | gateway | web | Kết quả lệnh cần trả lời (`send_files`): web `BLPOP` có timeout |
| `zalo:gw:hb:{shard}` | string, TTL 30s | gateway | scheduler, trang health | Nhịp tim gateway |
| `zalo:ctx:{accountId}` | string (mã hoá), TTL 12h | gateway, job login | web, queue | Ngữ cảnh phiên để gọi HTTP API Zalo (mục 4) |
| `zalo:session:{accountId}` | hash | gateway | web | `state`, `connected_at`, `last_event_at`, `last_error` |
| `zalo:qr:{accountId}` | string, TTL 120s | job login QR | web | Ảnh QR PNG base64 + trạng thái quét |
| `zalo:ver:{accountId}` | integer | consumer (INCR) | web | Số phiên bản dữ liệu chat; UI hỏi rẻ để biết có gì mới (7.6) |
| `zalo:hidden:{accountId}` | string JSON, TTL 60s | service hội thoại ẩn | consumer, web | Danh sách thread đang ẩn |
| `zalo:contacts:{accountId}` | string JSON, TTL 10 phút | ZaloContactService | web | Danh bạ (bạn bè + nhóm) |
| `zalo:sticker:{id}` | string, không TTL | gateway/web | web | Chi tiết sticker (tài nguyên tĩnh) |

Redis PHẢI cấu hình `maxmemory-policy noeviction` (Redis vừa là cache vừa là hàng đợi; `allkeys-lru`
sẽ âm thầm xoá tin đang chờ ghi) và bật AOF (`appendonly yes`, `appendfsync everysec`).

### 2.4 Vì sao gateway dùng event loop

Một tài khoản = một WebSocket sống 24/7 + một timer ping. 100 tài khoản trong một tiến trình PHP
đồng bộ là không thể; với event loop (ReactPHP) một tiến trình giữ được vài trăm kết nối, RAM
ước tính 10–30 MB/tài khoản ở bản Node cũ (bản PHP cần đo lại ở Phase 0).

zca-php đã chạy sẵn trên ReactPHP: `Zca\Apis\Listener` dùng **event loop toàn cục**
(`React\EventLoop\Loop`) và Pawl, ping bằng `Loop::addPeriodicTimer` theo
`settings.features.socket.ping_interval`, mỗi frame xử lý trong `React\Async\async()` (fiber). Nhờ
vậy N listener của N tài khoản sống chung một tiến trình: gateway gọi `$api->listener->start()` cho
từng tài khoản rồi chạy **một** `Loop::run()` duy nhất — **KHÔNG** gọi `$api->listener->run()` theo
từng tài khoản (nó chính là `Loop::run()`, sẽ chặn ở tài khoản đầu tiên).

**Quy tắc cho gateway:** trong callback của event loop **KHÔNG ĐƯỢC** gọi I/O chặn lâu (truy vấn
MySQL nặng, `Http::` đồng bộ). Chỉ RPUSH Redis (dưới 1ms) và cập nhật state trong RAM. Mọi ghi DB để
consumer làm. Lưu ý riêng với zca-php: **mọi lời gọi API của gói (kể cả `login`) là Guzzle đồng bộ**
— chạy trong fiber cũng vẫn chặn cả tiến trình, mọi WebSocket khác đứng chờ. Vì vậy trong gateway
chỉ được gọi API zca-php ở những chỗ bắt buộc (đăng nhập lại, `send_files`, `pull_mobile_msg`) và
phải đo thời gian chặn; tra cứu phụ (sticker, hồ sơ) đẩy cho consumer/queue.

### 2.5 Cấu trúc thư mục đề xuất

```
app/
  Zalo/Protocol/                 ← lớp bọc mỏng quanh eric-sa/zca-php; nơi DUY NHẤT được `use Zca\…`
    ZcaFactory.php               tạo Zca\Zalo với options chuẩn (logger, checkUpdate=false, uploadTimeout, proxy)
    ZaloContext.php              serialize/khôi phục Zca\Context ↔ mảng cho Redis zalo:ctx (4.1)
    ZaloLoginQr.php              bọc Zalo::loginQR, đổi LoginQRCallbackEventType → sự kiện 4.2
    ZaloLoginCookie.php          bọc Zalo::login, dịch lỗi → ZaloAuthExpired
    ZaloApi.php                  bọc Zca\API: sendText, uploadAttachment, getAllFriends… (4.3), dịch ZaloApiError
    ZaloListener.php             bọc Zca\Apis\Listener: on('message'|'reaction'|'undo'|…) (4.4)
    Extensions/                  phần zca-php CHƯA có: ZNoise (custom API, 4.6.9)
    MessageNormalizer.php        Zca\Models\UserMessage|GroupMessage|… → NormalizedMessage
    ImageSize.php                đọc width/height (bọc getimagesizefromstring)
    Errors/                      ZaloSessionNotReady, ZaloAuthExpired, ZaloApiException (lỗi CỦA DỰ ÁN, không lộ Zca\Errors ra ngoài)
  Zalo/MobileSync/               ← F16, TỰ VIẾT (zca-php không có), không phụ thuộc Laravel/zca-php
    ZaloDbCryptDecoder.php       bước 6 → 9: khoá → AES theo khối → ZDB4 → XZ → SQLite (mã đầy đủ ở 4.6.8a)
    MobileSyncException.php
  Zalo/Gateway/
    GatewayRunner.php            event loop, quản lý N phiên
    GatewaySession.php           1 tài khoản: WS, cipher key, ping, reconnect
    CommandPoller.php            đọc zalo:gw:cmd:{shard}
    IngestPublisher.php          RPUSH zalo:ingest
  Console/Commands/
    ZaloGatewayCommand.php       zalo:gateway
    ZaloConsumeCommand.php       zalo:consume
    ZaloCreateAdminCommand.php   user:create-admin
  Http/Controllers/Zalo/         ZaloAccountController, ZaloChatController, ZaloContactController,
                                 ZaloFriendController, ZaloGroupController
  Http/Requests/Zalo/            SendMessageRequest, StoreZaloAccountRequest, …
  Http/Middleware/               EnsureZaloAccountAccess, EnsureUserIsAdmin
  Services/Zalo/                 ZaloAccountService, ZaloSessionService, ZaloChatService,
                                 ZaloSendService, ZaloMessageIngestService, ZaloEventIngestService,
                                 ZaloContactService, ZaloHiddenConversationService, ZaloErrorTranslator
  Repositories/Zalo/             ZaloAccountRepository, ZaloConversationRepository,
                                 ZaloMessageRepository, ZaloContactRepository, …
  Jobs/Zalo/                     ZaloQrLoginJob, PruneConversationMessagesJob, ResolveProfilesJob
resources/views/zalo/            chat.blade.php, accounts.blade.php, partials/*
public/zalo/                     chat.js, accounts.js, chat.css (JS/CSS thuần, không build)
config/zalo.php
```

### 2.6 `config/zalo.php`

```php
return [
    'gateway' => [
        'shards'              => (int) env('ZALO_GATEWAY_SHARDS', 1),
        'restore_gap_ms'      => (int) env('ZALO_RESTORE_GAP_MS', 200),      // nghỉ giữa 2 lần đăng nhập lại khi khởi động (login zca-php là đồng bộ, xem 5.4)
        'reconnect_min_ms'    => 1000,
        'reconnect_max_ms'    => 30000,
        'command_poll_ms'     => 250,
        'ingest_high_watermark' => (int) env('ZALO_INGEST_HIGH_WATERMARK', 50000),
    ],
    'consumer' => [
        'batch_size'     => (int) env('ZALO_INGEST_BATCH_SIZE', 200),
        'flush_ms'       => (int) env('ZALO_INGEST_FLUSH_MS', 500),
    ],
    'http' => [   // truyền vào zca-php qua ZcaFactory (httpClient Guzzle có timeout, option uploadTimeout)
        'timeout'        => (int) env('ZALO_HTTP_TIMEOUT', 30),
        'upload_timeout' => (int) env('ZALO_UPLOAD_TIMEOUT', 120),   // = option `uploadTimeout` của zca-php (mặc định gói là 300s)
        'proxy'          => env('ZALO_PROXY'),                        // = option `proxy` của zca-php, null = không dùng
        'user_agent'     => env('ZALO_USER_AGENT', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36'),
        'language'       => 'vi',
    ],
    'attachments' => [   // NGUỒN SỰ THẬT về trần tệp, xem 9.3
        'max_files'    => 5,
        'max_image_mb' => 5,
        'max_video_mb' => 15,
        'max_file_mb'  => 15,
        'max_total_mb' => 20,
    ],
    'messages' => [
        'page_size'               => 50,
        'keep_per_conversation'   => (int) env('ZALO_KEEP_PER_CONVERSATION', 0), // 0 = giữ hết; >0 = prune (9.2)
    ],
    'debug_log'              => (bool) env('ZALO_DEBUG_LOG', false),   // bật log nội bộ của zca-php vào kênh 'zalo'; chỉ bật khi điều tra
    'hidden_cache_seconds'   => 60,
    'contacts_cache_minutes' => 10,
    'profile_ttl_days'       => 7,     // ảnh/tên đã có
    'profile_empty_ttl_hours'=> 12,    // Zalo trả rỗng
];
```

---

## 3. MÔ HÌNH DỮ LIỆU

Tất cả bảng dữ liệu Zalo khoá theo `zalo_account_id`. **KHÔNG** dùng `cascadeOnDelete` từ
`zalo_accounts` xuống bảng tin nhắn: xoá tài khoản là **xoá mềm** (mục 5.16), dữ liệu tin nhắn phải
sống sót để đổi chủ sang bản ghi mới khi người dùng đăng nhập lại cùng tài khoản Zalo.

### 3.1 `users` (bổ sung vào bảng có sẵn)

| Cột | Kiểu | Ghi chú |
|---|---|---|
| `phone` | varchar(20) unique nullable | đăng nhập |
| `role` | varchar(20) default `staff` | `staff` \| `admin` |
| `chat_active_zalo_account_ids` | json nullable | các tài khoản đang tích chọn ở màn chat (thói quen từng người) |

### 3.2 `zalo_accounts`

| Cột | Kiểu | Ghi chú |
|---|---|---|
| `id` | bigint PK | |
| `user_id` | bigint nullable, index | người tạo/chủ sở hữu; xoá nhân viên → `NULL` (không xoá tài khoản Zalo) |
| `name` | varchar(255) | tên gợi nhớ: "Zalo Sale 01" |
| `zalo_uid` | varchar(64) nullable, index | id Zalo cấp, chỉ biết **sau** khi đăng nhập |
| `zalo_display_name` | varchar(255) nullable | tên Zalo của chính tài khoản |
| `zalo_avatar_url` | text nullable | |
| `status` | varchar(32) default `CREATED` | xem 5.1 |
| `last_seen_at` | timestamp nullable | lần cuối nhận sự kiện |
| `logged_in_at` | timestamp nullable | |
| `relogin_required_at` | timestamp nullable | |
| `last_error` | text nullable | câu tiếng Việt cho người vận hành |
| `is_enabled` | boolean default true | |
| `gateway_shard` | smallint default 0 | `id % shards` khi tạo |
| `mobile_sync_seq_id` | bigint default 0 | con trỏ `from_seq_id` của lần đồng bộ từ điện thoại gần nhất (4.6.12) |
| `timestamps`, `deleted_at` | | **soft delete** |

### 3.3 `zalo_credentials`

Tách bảng riêng để không bao giờ lỡ tay `toArray()` lộ ra API.

| Cột | Kiểu | Ghi chú |
|---|---|---|
| `zalo_account_id` | bigint PK | |
| `payload` | longtext | `Crypt::encryptString(json_encode(['imei'=>…, 'cookie'=>[…], 'userAgent'=>…, 'language'=>'vi']))` |
| `updated_at` | timestamp | |

Model PHẢI có `$hidden = ['payload']`. Không log `payload`, `cookie`, `imei`.

### 3.4 `zalo_conversations`

| Cột | Kiểu | Ghi chú |
|---|---|---|
| `id` | bigint PK | |
| `zalo_account_id` | bigint | |
| `thread_id` | varchar(64) | id thật của Zalo (uid người hoặc id nhóm) |
| `thread_type` | enum(`user`,`group`) default `user` | **bắt buộc khi gửi** — cùng một id có thể là người hoặc nhóm |
| `display_name` | varchar(255) nullable | tên từ Zalo; bị **ghi đè** bởi danh bạ ở mỗi lượt đọc |
| `custom_name` | varchar(255) nullable | tên người dùng tự đặt; ưu tiên cao nhất |
| `avatar_url` | text nullable | |
| `is_hidden` | boolean default false | hội thoại ẩn bên Zalo (5.13) |
| `last_message_preview` | text nullable | |
| `last_message_at` | timestamp(3) nullable | |
| `last_message_direction` | enum(`in`,`out`) nullable | |
| `unread_count` | unsigned int default 0 | **luôn tính lại từ DB**, không cộng dồn (5.7) |
| `last_read_at` | timestamp(3) nullable | mốc đọc = `sent_at` của tin mới nhất lúc mở, KHÔNG phải `now()` |
| `deleted_at` | timestamp nullable | xoá hội thoại khỏi hệ thống = xoá mềm |
| `timestamps` | | |

Index: `UNIQUE(zalo_account_id, thread_id)`;
`INDEX zalo_conv_visible_idx (zalo_account_id, is_hidden, last_message_at, id)` (sidebar phân trang).

### 3.5 `zalo_messages`

| Cột | Kiểu | Ghi chú |
|---|---|---|
| `id` | bigint PK | |
| `zalo_account_id` | bigint | |
| `zalo_conversation_id` | bigint | |
| `msg_id` | varchar(64) | id tin của Zalo — **chốt chặn chống trùng duy nhất** |
| `cli_msg_id` | varchar(64) nullable | id phía client |
| `thread_id` | varchar(64) | |
| `thread_type` | enum(`user`,`group`) | |
| `direction` | enum(`in`,`out`) | `out` = do chính tài khoản này gửi (từ tool hoặc từ điện thoại) |
| `sender_id` | varchar(64) nullable | |
| `sender_name` | varchar(255) nullable | |
| `content` | longtext nullable | chữ thuần (đã tách đính kèm) |
| `msg_type` | varchar(64) nullable | `webchat`, `chat.photo`, `chat.sticker`, `share.file`, `chat.video.msg`, `chat.recommended`, `chat.link`, `chat.voice`… |
| `attachments` | json nullable | xem 3.5.1 |
| `mentions` | json nullable | `[{uid, pos, len, type}]` |
| `quote_msg_id` | varchar(64) nullable | tin này trả lời tin nào |
| `quote_payload` | json nullable | **bản thô** để về sau trích dẫn CHÍNH tin này (mục 5.10). Giữ nguyên khoá camelCase của Zalo |
| `quote_preview` | json nullable | `{senderName, text}` của tin được trích (khi tin gốc không có trong kho) |
| `is_recalled` | boolean default false | đã bị thu hồi |
| `recalled_at` | timestamp nullable | |
| `sent_at` | timestamp(3) | thời gian **Zalo cấp** (`ts`, mili giây) |
| `timestamps` | | |

Index (đã đo cho 50 triệu dòng):

```sql
UNIQUE KEY uq_msg (zalo_account_id, msg_id)
KEY zalo_msg_conv_timeline_idx (zalo_conversation_id, sent_at, id)            -- đọc trang, prune
KEY zalo_msg_conv_dir_sent_msg_idx (zalo_conversation_id, direction, sent_at, msg_id) -- đếm chưa đọc
```

KHÔNG thêm index đơn `(sent_at)` hay `(zalo_conversation_id, sent_at)` — thừa, làm chậm mọi insert.
KHÔNG partition bảng live (MySQL không cho FK trên bảng partition và unique key phải chứa cột
partition).

#### 3.5.1 Hình dạng `attachments[]`

```json
{
  "type": "image | video | file | audio | sticker | link | card",
  "url": "https://…",            // đường dẫn CDN Zalo (có hạn dùng)
  "thumb_url": "https://…",      // ảnh thu nhỏ
  "name": "bao-gia.pdf",
  "size": 123456,
  "mime": "application/pdf",
  "width": 1280, "height": 720,
  "duration": 12000,             // video/audio, ms
  "sticker_id": 123, "cate_id": 45,
  "title": "…", "description": "…"   // link/card
}
```

Lọc URL khi ghi: chỉ chấp nhận `https://` (và `http://` nếu là miền Zalo); bỏ `javascript:`, `data:`.

### 3.6 Bảng phụ

| Bảng | Cột chính | Unique | Vai trò |
|---|---|---|---|
| `zalo_contacts` | `zalo_account_id`, `contact_id`, `contact_type`(user/group), `display_name`, `zalo_name`, `avatar_url`, `is_friend` bool, `synced_at` | `(zalo_account_id, contact_id)` | Cache tên/ảnh người & nhóm (kể cả người lạ) |
| `zalo_message_reactions` | `zalo_account_id`, `msg_id`, `thread_id`, `thread_type`, `actor_id`, `actor_name`, `icon`(chuẩn hoá), `raw_icon`, `reacted_at` | `(zalo_account_id, msg_id, actor_id)` | Reaction thật của mọi người |
| `zalo_friend_requests` | `zalo_account_id`, `from_uid`, `from_name`, `message`, `status`(pending/accepted/rejected/undone), `requested_at`, `resolved_at` | `(zalo_account_id, from_uid)` | Lời mời kết bạn đến |
| `zalo_agent_sent_messages` | `zalo_account_id`, `msg_id`, `created_at` | `(zalo_account_id, msg_id)` | Tin do AI/tự động gửi → không tính là "đã đọc" (5.7) |
| `zalo_user_sent_messages` | `zalo_account_id`, `msg_id`, `user_id` | `(zalo_account_id, msg_id)` | Nhân viên nào bấm gửi (hiển thị + báo cáo) |
| `zalo_account_user` | `zalo_account_id`, `user_id` | cặp | Giao tài khoản Zalo cho nhân viên |
| `tags` | `name` unique, `color` #hex, `category` | | Thẻ phân loại |
| `conversation_tag` | `tag_id`, `zalo_conversation_id` | cặp | |
| `message_templates` | `code` unique (không có `/`), `content` | | Tin mẫu `/code` |
| `zalo_mobile_sync_runs` | `zalo_account_id`, `status` (4.6.3), `public_key` text, `private_key` text (mã hoá, NULL khi xong), `retry_count`, `from_seq_id`, `is_full_transfer`, `expected_total`, `expected_threads`, `imported`, `database_count`, `reason`, `detail` json, timestamps | | Mục 4.6 / 5.17 (tuỳ chọn) |

Khi bảng nào chống trùng theo `(tài khoản, khoá)`, thao tác "đổi chủ" (5.16) PHẢI xoá bản ghi
đụng nhau trước khi `UPDATE zalo_account_id` (giữ bản của tài khoản MỚI).

---

## 4. GIAO THỨC ZALO VÀ THUẬT TOÁN MÃ HOÁ

> **Phạm vi của mục này.** Tầng đăng nhập/mã hoá phiên/WebSocket của Zalo **không tự viết**: dùng
> gói `eric-sa/zca-php` (namespace `Zca\`, mã nguồn `https://github.com/quangvv-dev/zca-php`, MIT).
> Gói là bản PHP của `zca-js@2.2.0` (`https://github.com/RFS-ADRENO/zca-js`): giữ nguyên endpoint,
> tham số, mã hoá, thông báo lỗi; API cùng tên và thứ tự đối số; khác ở chỗ gọi **đồng bộ** (không
> `await`), enum thành hằng số (`Zca\Models\ThreadType::User`), object thành mảng kết hợp, tệp
> đính kèm là `["data" => $bytes, "filename" => …, "metadata" => [...]]`.
>
> Mục này đặc tả **hợp đồng** mà lớp bọc `app/Zalo/Protocol` phải cung cấp cho phần còn lại của hệ
> thống (đầu vào, đầu ra, lỗi, bất biến) và **ánh xạ** từng hợp đồng sang zca-php. Thuật toán giải mã
> do dự án **tự viết** (đồng bộ lịch sử từ điện thoại) — phần zca-php không có — được đặc tả tới từng
> byte ở **4.6**. Hệ thống cũ (`worker/node_modules/zca-js/dist/` + `worker/patches/zca-js+2.1.2.patch`,
> lớp dùng ở `worker/src/zalo/*.ts`) chỉ còn là **tài liệu đối chiếu hành vi**, không phải nguồn để port.
> Đội triển khai tự chịu trách nhiệm đánh giá điều khoản sử dụng của Zalo (xem 0.3).
>
> **Đồng bộ từ điện thoại (F16):** từ zca-php **2.1.0** gói đã có `pullMobile()` (`pull_mobile_msg`),
> sự kiện listener `sync_event` (`act_type="syncmsgmb"`), `getSyncData()` và tiện ích RSA — tương đương
> bản vá zca-js của worker cũ. Thứ duy nhất còn thiếu là API `znoise` (4.6.9), bổ sung bằng custom API.
> Mọi tính năng F1–F15 dùng được API sẵn có của gói.
>
> Nếu zca-php gãy (Zalo đổi giao thức mà gói chưa cập nhật), hai đường dự phòng vẫn giữ nguyên phần
> còn lại của tài liệu (mục 3, 5–12): (a) chạy tạm một worker nhỏ dùng `zca-js` bản mới, đẩy vào chính
> `zalo:ingest` và nhận lệnh từ `zalo:gw:cmd:*`; (b) chỉ dùng **Zalo OA OpenAPI chính thức** (phụ lục B)
> — là kênh OA, không phải nick cá nhân.

### 4.1 Hợp đồng `ZaloContext` (ngữ cảnh phiên)

```php
final class ZaloContext {
    public string $accountId;      // id trong hệ thống
    public string $uid;            // Zca\Context::$uid — id Zalo của chính tài khoản
    public string $imei;           // Zca\Context::$imei — sinh lúc quét QR, phải giữ cố định cho credential đó
    public string $userAgent;      // Zca\Context::$userAgent — phải giữ đúng UA đã dùng lúc quét QR
    public string $language;       // Zca\Context::$language — "vi"
    public array  $cookies;        // Zca\Context::$cookie->toJSON() (CookieJar → mảng)
    public string $secretKey;      // Zca\Context::$secretKey (= zpw_enk) — khoá mã hoá tham số API
    public array  $serviceMap;     // Zca\Context::$zpwServiceMap — nhóm dịch vụ → base URL (chat, group, file…)
    public array  $wsUrls;         // loginInfo["zpw_ws"] — danh sách URL WebSocket
    public array  $settings;       // Zca\Context::$settings — giới hạn server trả về (tệp, socket.ping_interval…)
    public array  $loginInfo;      // Zca\Context::$loginInfo — một số API cần (vd. send2me_id)
    public ?array $extraVer;       // Zca\Context::$extraVer — getUserInfo cần phonebook_version
}
```

- Credential lưu bền (`zalo_credentials`) = `{imei, cookie, userAgent, language}` — **đúng hình dạng
  mảng `$credentials` mà `Zca\Zalo::login()` nhận** (`cookie` là danh sách cookie). Cookie/imei xuất từ
  `zca-js` của hệ thống cũ dùng được nguyên, nên khi chuyển hệ thống KHÔNG cần quét QR lại.
- `ZaloLoginCookie::login()` = `ZcaFactory::make()->login($credentials)` → `Zca\API`; `ZaloContext`
  lấy từ `$api->getContext()` (API `GetContext` của gói) rồi ghi vào Redis `zalo:ctx:{id}` (mã hoá bằng
  `Crypt` — trong đó có `secretKey` và cookie).
- **Dựng lại `Zca\API` ở tiến trình web mà không đăng nhập lại:** tạo `Zca\Context::create()`, gán lại
  các trường trên (cookie qua `CookieJar::setCookieFromJSON()` từng phần tử), rồi
  `new Zca\API($ctx, $serviceMap, $wsUrls)` (constructor public, chỉ đòi `secretKey` khác rỗng; không mở
  WebSocket). `ZaloContext::toZcaApi()` gom việc này. KHÔNG gọi `Zalo::login()` ở web: mỗi lần tốn 2
  request HTTP và có thể đổi khoá phiên.
- zca-php tự cập nhật CookieJar khi phản hồi có `Set-Cookie`. Gateway (nơi giữ `Zca\API` sống lâu)
  PHẢI định kỳ (mỗi 30 phút) và khi dừng ghi lại `cookie->toJSON()` vào credential + `zalo:ctx`, để lần
  khôi phục sau dùng cookie mới nhất. Cookie thay đổi ở tiến trình web bị bỏ (chấp nhận).
- Chỉ **gateway** (và job QR) được gọi đăng nhập. Tiến trình web chỉ **đọc** `zalo:ctx`. Lý do: một
  lần đăng nhập mới có thể làm đổi khoá phiên; nhiều tiến trình cùng đăng nhập sẽ dẫm lên nhau
  (chưa xác minh hành vi thật — giữ nguyên tắc an toàn). Web gặp lỗi xác thực từ Zalo → RPUSH lệnh
  `start` cho gateway và trả `SESSION_STARTING`.

### 4.2 Hợp đồng đăng nhập

```php
interface ZaloLoginQr {
    /** Chạy toàn bộ luồng QR. Gọi $onEvent mỗi khi trạng thái đổi. Trả credential khi xong. */
    public function run(callable $onEvent, int $maxRefresh = 3): ZaloCredential;
    // $onEvent nhận: ['type'=>'qr','image'=>base64Png,'expires_in'=>s]
    //               ['type'=>'scanned','display_name'=>…,'avatar'=>…]
    //               ['type'=>'expired'] | ['type'=>'declined'] | ['type'=>'done']
}
interface ZaloLoginCookie {
    /** Đăng nhập lại bằng credential đã lưu. Ném ZaloAuthExpired nếu Zalo từ chối. */
    public function login(ZaloCredential $c): ZaloContext;
}
```

- Job QR ghi mỗi sự kiện vào `zalo:qr:{id}` (TTL 120s) cho UI poll (5.3). Hết hạn tự lấy mã mới tối
  đa `$maxRefresh` lần. Người dùng bấm từ chối trên điện thoại → `declined`, UI báo "Đã từ chối đăng nhập trên điện thoại".
- Dùng **một User-Agent Chrome desktop cố định** (`config('zalo.http.user_agent')`) và giữ đúng UA
  đó cho mọi lần khôi phục credential. Hệ thống cũ dùng chế độ đăng nhập kiểu ứng dụng PC; chế độ
  kiểu web từng làm Zalo báo lỗi khi kiểm tra phiên.
- Không có đăng nhập mật khẩu, không bypass captcha/OTP.

**Ánh xạ sang zca-php** (`Zca\Zalo::loginQR(array $options, callable $callback)`):

| Sự kiện zca-php (`Zca\Models\LoginQRCallbackEventType`) | `$event["data"]` | Sự kiện hợp đồng | Việc lớp bọc làm |
|---|---|---|---|
| `QRCodeGenerated` | `image` (PNG base64 đã bỏ tiền tố), `code`… | `qr` | ghi `zalo:qr:{id}`; **không** gọi `actions.saveToFile()` |
| `QRCodeScanned` | tên + ảnh đại diện người quét | `scanned` | ghi `scanned_name`, `scanned_avatar` |
| `QRCodeExpired` | `null` | `expired` | còn lượt (< `$maxRefresh`) → gọi `$event["actions"]["retry"]()`; hết lượt → không gọi gì, gói ném `ZaloApiLoginQRAborted` |
| `QRCodeDeclined` | `code` | `declined` | không gọi `retry`; gói ném `Zca\Errors\ZaloApiLoginQRDeclined` |
| `GotLoginInfo` | `cookie`, `imei`, `userAgent` | `done` | đây chính là credential → mã hoá, lưu `zalo_credentials` |

Quy tắc khi gọi `loginQR`:

- **PHẢI truyền callback.** Không có callback, gói tự ghi `qr.png` vào thư mục làm việc (rò ảnh QR ra đĩa).
- **PHẢI truyền `userAgent` = `config('zalo.http.user_agent')`.** Bỏ trống, gói dùng UA Firefox 133
  mặc định — lệch với UA mà mọi lần khôi phục sau đó dùng.
- `loginQR` **chặn** tới `LoginQR::QR_TIMEOUT` = 100 giây mỗi mã (chờ quét + chờ xác nhận là long-poll
  đồng bộ) → chỉ chạy trong `ZaloQrLoginJob` (queue `zalo-login`, `timeout` ≥ 330s cho 3 lần làm mới),
  không bao giờ trong request web hay gateway.
- Sau `GotLoginInfo`, gói **tự đăng nhập bằng cookie** và trả `Zca\API`. Job bỏ đối tượng đó, không mở
  listener — vẫn RPUSH `start` cho gateway như 5.3 (giữ nguyên tắc chỉ gateway giữ phiên).
- `ZaloLoginCookie` bắt `Zca\Errors\ZaloApiError` từ `Zalo::login()` (vd. "Đăng nhập thất bại",
  thiếu `zpw_enk`) → ném `ZaloAuthExpired`; lỗi mạng (Guzzle `ConnectException`) → ném lỗi tạm thời để
  gateway thử lại theo backoff, **không** chuyển RELOGIN_REQUIRED.

### 4.3 Hợp đồng HTTP API

```php
interface ZaloApi {
    // Nhắn tin
    public function sendText(ZaloContext $c, string $threadId, string $threadType, string $text,
                             ?array $quotePayload = null, array $mentions = []): SendResult;   // msgId, cliMsgId
    public function uploadAttachment(ZaloContext $c, string $threadId, string $threadType,
                                     string $bytes, string $fileName, string $mime, ?array $imageSize): UploadedAttachment;
    public function sendAttachments(ZaloContext $c, string $threadId, string $threadType,
                                    array $uploaded, string $caption = ''): SendResult;
    public function sendSticker(ZaloContext $c, string $threadId, string $threadType, int $stickerId, int $cateId, int $type): SendResult;
    public function sendCard(...); public function sendVideo(...); public function sendBankCard(...);
    public function addReaction(ZaloContext $c, array $targetMessage, string $icon): void;
    public function undo(ZaloContext $c, array $targetMessage): void;
    public function deleteForMe(ZaloContext $c, array $targetMessage): void;
    public function forwardText(ZaloContext $c, string $text, array $threadIds, string $threadType): array;
    // Tra cứu
    public function getAllFriends(ZaloContext $c): array;       // [{uid, displayName, zaloName, avatar, phone?}]
    public function getAllGroups(ZaloContext $c): array;        // [groupId]
    public function getGroupInfo(ZaloContext $c, array $groupIds): array;   // tên, ảnh, memberIds
    public function getUserInfo(ZaloContext $c, array $uids): array;
    public function getGroupMembersInfo(ZaloContext $c, array $uids): array;
    public function getHiddenConversations(ZaloContext $c): array;           // [threadId]  (bỏ PIN ngay)
    public function getStickersDetail(ZaloContext $c, array $ids): array;
    public function searchStickers(ZaloContext $c, string $keyword): array;
    public function findUserByPhone(ZaloContext $c, string $phone): ?array;
    // Bạn bè / nhóm
    public function sendFriendRequest(...); acceptFriendRequest(...); rejectFriendRequest(...);
    public function undoFriendRequest(...); removeFriend(...); getFriendRequestStatus(...);
    public function createGroup(...); addGroupMembers(...); removeGroupMembers(...);
    public function changeGroupName(...); changeGroupAvatar(...);
}
```

Bất biến chung cho mọi lời gọi:

- Mọi lời gọi đều cần `ZaloContext` hợp lệ. Thiếu → `ZaloSessionNotReady`.
- Phản hồi Zalo có mã lỗi khác 0 → ném `ZaloApiError(code, message)`; tầng Service dịch qua Phụ lục A.
  Lỗi xác thực/phiên → `ZaloAuthExpired` (gateway chuyển RELOGIN_REQUIRED).
- Timeout: 30s cho lời gọi thường, 120s cho upload.
- `$targetMessage` cho reaction/undo/delete là `{msgId, cliMsgId, threadId, threadType, uidFrom?}` lấy
  từ `zalo_messages`.
- `quotePayload` là bản thô `quote_payload` đã lưu (5.10); tầng API chuyển nó nguyên vẹn sang dạng
  trả lời của Zalo. Loại tin không trích dẫn được (bình chọn nhóm, `webchat` dạng object) có
  `quote_payload = null` ngay từ lúc nhận.
- Ảnh PHẢI kèm `width`/`height` (`ImageSize::fromBytes()` bọc `getimagesizefromstring`).
- Danh sách đuôi tệp bị cấm và trần dung lượng phía Zalo nằm trong `ZaloContext::$settings`; kiểm tra
  trước khi upload và trả `ATTACHMENT_INVALID` kèm lý do tiếng Việt.

**Ánh xạ sang zca-php.** `ZaloApi` (lớp của dự án) nhận `ZaloContext`, dựng `Zca\API` qua
`ZaloContext::toZcaApi()` (4.1) rồi gọi phương thức cùng tên của gói. `$type` là
`Zca\Models\ThreadType::User` / `::Group` (lớp bọc đổi từ chuỗi `user|group`).

| Hợp đồng `ZaloApi` | zca-php (`$api->…`) | Ghi chú |
|---|---|---|
| `sendText` (có quote / mention) | `sendMessage(array\|string $message, $threadId, $type)` | `$message` dạng mảng: `msg`, `quote`, `mentions`, `styles`, `ttl`; `quote` = `quote_payload` đã lưu (chính là `$message->data` thô lúc nhận, 4.5) |
| `uploadAttachment` + `sendAttachments` | `uploadAttachment($sources, $threadId, $type)` hoặc `sendMessage(["msg" => caption, "attachments" => [...]], …)` | nguồn từ bộ nhớ: `["data" => $bytes, "filename" => …, "metadata" => ["width", "height", "totalSize"]]`; **video/tệp chỉ chạy trong gateway** (5.10) |
| `sendSticker` | `sendSticker(array $sticker, $threadId, $type)` | |
| `sendCard` / `sendVideo` / `sendBankCard` | `sendCard` / `sendVideo` / `sendBankCard` | `sendVideo` gửi video theo URL, không upload |
| `addReaction` | `addReaction($icon, ["data" => ["msgId", "cliMsgId"], "threadId", "type"])` | icon: `Zca\Models\Reactions::*` |
| `undo` | `undo($payload, $threadId, $type)` | |
| `deleteForMe` | `deleteMessage($dest, onlyMe: true)` | |
| `forwardText` | `forwardMessage($payload, $threadIds, $type)` | |
| `getAllFriends` / `getAllGroups` / `getGroupInfo` / `getUserInfo` / `getGroupMembersInfo` | cùng tên | |
| `getHiddenConversations` | `getHiddenConversations()` | |
| `getStickersDetail` / `searchStickers` | `getStickersDetail` / `searchSticker($keyword, $limit)` | |
| `findUserByPhone` | `findUser($phone)` | |
| `sendFriendRequest` … `getFriendRequestStatus` | `sendFriendRequest`, `acceptFriendRequest`, `rejectFriendRequest`, `undoFriendRequest`, `removeFriend`, `getFriendRequestStatus` | |
| `createGroup` … `changeGroupAvatar` | `createGroup`, `addUserToGroup`, `removeUserFromGroup`, `changeGroupName`, `changeGroupAvatar` | |
| (F16) `pullMobileMsg` / `downloadSyncData` | `pullMobile(array $params)` / `getSyncData([... 'returnStream' => true])` | từ 2.1.0; chi tiết 4.6.2 |
| (F16) `znoise` | **chưa có** — đăng ký bằng `$api->custom('znoise', fn(array $p) => …)` (4.6.2) | |

Danh sách đầy đủ chữ ký: `src/ApiMethods.php` của gói. Trước khi dùng một phương thức, đọc lớp
`src/Apis/<Tên>.php` tương ứng để biết hình dạng mảng trả về — tài liệu này không chép lại.

Lỗi: zca-php ném `Zca\Errors\ZaloApiError` (`getMessage()` = thông báo của Zalo, `$zaloCode` = mã lỗi
Zalo hoặc `null`). `ZaloApi` bắt và ném lại `ZaloApiException(code, message)` của dự án; mã thuộc nhóm
phiên/xác thực → `ZaloAuthExpired`. Bảng mã Zalo → nhóm lỗi nằm trong `ZaloErrorTranslator` và PHẢI có
test. Lỗi Guzzle (`ConnectException`, `RequestException` timeout) giữ nguyên ý nghĩa ở 5.10 (lỗi
trước khi gửi → được retry; timeout sau khi gửi → `SEND_UNCERTAIN`).

`ZcaFactory::make()` luôn truyền cho `new Zca\Zalo($options)`:

```php
[
    'checkUpdate'  => false,                         // mặc định true: MỖI lần login gọi registry.npmjs.org — không được có ở production
    'logger'       => Log::channel('zalo'),          // PSR-3; không truyền thì gói in ra stdout
    'logging'      => (bool) config('zalo.debug_log', false),
    'httpClient'   => new \GuzzleHttp\Client(['timeout' => config('zalo.http.timeout')]),
    'uploadTimeout'=> config('zalo.http.upload_timeout'),
    'proxy'        => config('zalo.http.proxy'),
    'selfListen'   => true,                          // PHẢI bật: tin tự gửi (từ điện thoại/tool) cần về để ghi direction=out (5.5)
]
```

### 4.4 Hợp đồng WebSocket (gateway)

```php
interface ZaloListener {
    public function connect(ZaloContext $c): void;                 // không chặn, chạy trên event loop
    public function onMessage(callable $cb): void;                 // tin thô 1-1 hoặc nhóm → MessageNormalizer
    public function onEvent(callable $cb): void;                   // reaction | undo | group | friend | sync_event | seen | delivered | typing
    public function onConnected(callable $cb): void;               // đã nhận khoá giải mã, sẵn sàng
    public function onClosed(callable $cb): void;                  // (int $code, string $reason)
    public function requestOldMessages(string $threadType): void;  // xin tin tồn (5.15), chỉ sau onConnected
    public function close(int $code = 1000): void;
}
```

Hành vi bắt buộc (rút từ vận hành hệ thống cũ):

- Kết nối xong phải chờ server gửi khoá giải mã cho phiên socket rồi mới coi là READY; frame tới
  trước đó → giữ đệm hoặc bỏ có log.
- Nhịp giữ kết nối (ping): zca-php tự lo (timer theo `settings.features.socket.ping_interval`, bắt đầu
  sau `cipher_key`). Gateway thêm watchdog: READY mà quá 3 chu kỳ ping không có frame nào → đặt cờ
  `watchdogTripped` rồi `stop()`; handler `closed` thấy cờ thì xử lý như rớt mạng (nối lại), không như
  đóng chủ động 1000.
- Mã đóng **1000**: đóng chủ động. **3000** (`DuplicateConnection` — tài khoản mở ở nơi khác) và
  **3003** (`KickConnection` — bị đá): KHÔNG tự nối lại, chuyển RELOGIN_REQUIRED, `last_error` ghi
  "Tài khoản đã đăng nhập Zalo Web/PC ở nơi khác — hãy quét QR lại". Mã khác / lỗi mạng → DISCONNECTED,
  tự nối lại với backoff 1s → 2s → 4s … tối đa 30s, có nhiễu ±20%; nối lại thành công thì reset backoff.
  Tự viết bộ đếm backoff (bộ nối lại `retryOnClose` của zca-php/zca-js không reset được và không theo quy tắc mã đóng này).
- Mỗi lần nối lại PHẢI đăng nhập lại bằng cookie nếu khoá phiên đã hết hạn.
- Xin tin tồn tự động **một lần** cho mỗi phiên (cờ `hasRequestedOldMessages`), và khi nhận lệnh thủ công.
- Các nhóm `cmd` hệ thống cũ đã quan sát: tin người dùng, tin nhóm, khung điều khiển (bao gồm sự kiện
  nhóm, bạn bè, đồng bộ từ điện thoại `act_type="syncmsgmb"`), phản hồi xin tin tồn, reaction, thu hồi.
  zca-php đã giải mã và phân loại sẵn (`Zca\Apis\Listener::handleMessage`), kể cả `syncmsgmb` →
  sự kiện `sync_event` (từ 2.1.0, 4.6.2).
- Nội dung frame có thể in ra log chỉ khi bật cờ debug có thời hạn (`ZALO_WS_DEBUG=1`), vì nó chứa nội dung tin nhắn.

**Ánh xạ sang zca-php.** `ZaloListener` bọc `$api->listener` (`Zca\Apis\Listener`, kế thừa
`Evenement\EventEmitter`); đăng ký bằng `->on($event, $cb)`, không dùng các hàm `onMessage()`/
`onConnected()`… đã deprecated của gói.

| Sự kiện zca-php | Đối số | Hợp đồng / việc gateway làm |
|---|---|---|
| `connected` | — | socket mở, **chưa** READY |
| `cipher_key` | `string $key` | đã có khoá giải mã → READY, RPUSH status; nếu chưa xin tin tồn thì `requestOldMessages` |
| `message` | `Zca\Models\UserMessage\|GroupMessage` (`threadId`, `type`, `isSelf`, `data` = tin thô) | `onMessage` → `MessageNormalizer` |
| `old_messages` | `array $messages, int $threadType` | như `message`, gắn `is_backfill=true` (5.15) |
| `reaction` / `old_reactions` | `Zca\Models\Reaction` / `array, bool $isGroup` | event `reaction` |
| `undo` | `Zca\Models\Undo` | event `undo` |
| `group_event` / `friend_event` | `Zca\Models\GroupEvent` / `FriendEvent` | event `group` / `friend` |
| `seen_messages` / `delivered_messages` / `typing` | mảng / model | tuỳ chọn; mặc định bỏ |
| `sync_event` | `Zca\Models\SyncEvent` (`type`, `act`, `act_type`, `data`) | event `mobile_sync` (4.6.2–4.6.3) |
| `upload_attachment` | `fileUrl`, `fileId` | gói tự dùng để kết thúc upload video/tệp; gateway không cần xử lý |
| `disconnected` / `closed` | `int $code, string $reason` | `onClosed` → logic mã đóng ở trên |
| `error` | `$error` | log (không log payload) |

Quy tắc dùng listener của gói:

- `start(["retryOnClose" => false])`. **Không** bật `retryOnClose`: bộ nối lại của gói lấy số lần/độ
  trễ từ `settings.features.socket` và không phân biệt 3000/3003 theo quy tắc trên. Gateway tự nối lại
  bằng backoff của mình: nhận `closed` → hẹn `Loop::addTimer()` → (đăng nhập lại nếu cần) → `start()` lại.
- `start()` ném "Already started" nếu socket cũ chưa dọn; chỉ gọi lại sau `closed`.
- Dừng chủ động: `$api->listener->stop()`; xin tin tồn: `requestOldMessages(ThreadType::User|Group, null)`.
- Mã 3000: gói tự đóng listener của mình khi bị phiên khác chiếm — gateway vẫn nhận `closed` và chuyển RELOGIN_REQUIRED.
- **Không** gọi `$api->listener->run()` trong gateway (2.4).

### 4.5 Hợp đồng `NormalizedMessage` (gateway → `zalo:ingest`)

```json
{
  "type": "message",
  "account_id": 2,
  "msg_id": "7340…", "cli_msg_id": "1730…",
  "thread_id": "8714…", "thread_type": "user|group",
  "direction": "in|out",
  "sender_id": "…", "sender_name": "…",
  "content": "chữ thuần (caption ảnh đưa vào đây)",
  "msg_type": "webchat|chat.photo|chat.sticker|share.file|chat.video.msg|chat.recommended|chat.link|chat.voice|…",
  "attachments": [ /* 3.5.1 */ ],
  "mentions": [{"uid":"…","pos":0,"len":5,"type":0}],
  "quote_msg_id": "…|null",
  "quote_payload": { /* bản thô đủ để trích dẫn CHÍNH tin này về sau, khoá camelCase nguyên gốc */ },
  "quote_preview": {"senderName":"…","text":"…"},
  "sent_at": "2026-11-02T10:24:31.512+07:00",
  "is_backfill": false
}
```

Quy tắc chuẩn hoá:

- Đầu vào từ zca-php: `UserMessage`/`GroupMessage` có `threadId` (gói đã đổi sẵn thành người nhận
  với tin 1-1 tự gửi), `type`, `isSelf`, `data` (tin thô, khoá camelCase của Zalo). `quote_payload` =
  `$message->data` nguyên vẹn — đúng dạng `sendMessage(["quote" => …])` cần.
- `direction="out"` khi người gửi là chính tài khoản (`$message->isSelf`, tức so với `ZaloContext::$uid`).
  `thread_id` của tin 1-1 tự gửi là **người nhận**, không phải mình — test PHẢI kiểm cả điều này,
  không tin hoàn toàn vào gói.
- `sent_at` từ timestamp mili giây của Zalo, giữ phần nghìn giây.
- `content` của ảnh/tệp/sticker bị tách sang `attachments`; vì thế `quote_payload` PHẢI chụp từ tin
  **thô** trước khi tách (không dựng ngược được từ dạng đã chuẩn hoá).
- Sticker: moi id theo thứ tự `id` → `stickerId` → `sticker_id` → `uri` → mẫu `[^cateId.stickerId^]` (5.5).
- Sự kiện: `{"type":"event","event":"reaction","account_id","msg_id","thread_id","thread_type","actor_id","actor_name","raw_icon","reacted_at"}`;
  `undo` có `msg_id`; `group` có `group_id`, `kind`, `name?`, `avatar?`; `friend` có `kind`, `uid`, `name?`, `message?`, `is_self`.
- Trạng thái: `{"type":"status","account_id","status","own_id?","display_name?","avatar?","error?"}`.

### 4.6 Đồng bộ lịch sử từ điện thoại — thuật toán giải mã TỰ VIẾT (đặc tả đầy đủ)

> Thư viện (bản vá zca-js PR #269 ở hệ thống cũ, và **zca-php từ 2.1.0** ở hệ thống mới) chỉ lo phần
> giao tiếp: gửi yêu cầu `pull_mobile_msg`, phát sự kiện `sync_event`, tải tệp `.db.crypt`, và mở gói
> RSA lấy 32 byte khoá AES (4.6.2, bước 5 ở 4.6.5). **Thư viện KHÔNG giải mã tệp**: từ bước 6 (dẫn xuất
> khoá thật) trở đi là mã tự viết của dự án (`worker/src/zalo/db-crypt.ts` ở hệ thống cũ), zca-php không có
> và không được chờ gói bổ sung. Mọi thứ sau đó — dò ra cách mã hoá tệp, bóc
> container ZDB4, giải nén, đọc SQLite, parse BinNet, map id, chuẩn hoá tin — do dự án tự viết và đã
> chạy thật: một tài khoản giải được **618 thread / 337.267 tin**. Nguồn tham chiếu:
> `worker/src/zalo/db-crypt.ts`, `sync-db-parser.ts`, `noise-id-resolver.ts`, `mobile-sync.ts`,
> `mobile-sync-store.ts`. Dưới đây là đặc tả để port sang PHP từng byte.

#### 4.6.1 Tổng quan pipeline

```
[1] sinh RSA-2048 tạm ─► [2] gửi pull_mobile_msg(public_key, from_seq_id)  (phản hồi rỗng)
        │
[3] chờ sự kiện ws "sync_event":  user_confirm ─► syncmsg_info{url, encrypted_key, file_size,
        │                                        checksum_code, from_seq_id, is_full_transfer, db_info}
        │                          transfer_error{can_retry, error_code, error_msg}
[4] tải url ra đĩa (stream) ─► kiểm size == file_size, md5 == checksum_code (sai → tải lại)
[5] aesKey(32 byte) = RSA_PKCS1_decrypt(privateKey, base64_decode(encrypted_key))
[6] key' = ASCII( UPPER( hex(aesKey) ) )[0..32]          ← khoá thật dùng cho AES
[7] .db.crypt ──AES-256-CBC, IV=0, KHÔNG padding, reset IV mỗi 64 KiB──► container "ZDB4.0"
[8] parse header ZDB4 ─► danh sách {name, size} + vùng nén XZ
[9] xzcat vùng XZ ─► cắt luồng ra theo size ─► N tệp SQLite (mỗi tệp = 1 thread)
[10] tên tệp ─► (plain_id, user|group) ─► tra noise id (id runtime) qua Zalo
[11] mỗi SQLite: đọc bảng ChatContent + cột BinNet ─► NormalizedMessage (is_backfill=true)
[12] ghi theo lô vào zalo_messages (ZaloMessageIngestService) ─► lưu from_seq_id ─► xoá tệp + khoá riêng
```

#### 4.6.2 Bước 1–2: cặp khoá RSA và yêu cầu đồng bộ

Từ **zca-php 2.1.0**, gói đã có sẵn bước 1–2 (port từ bản vá zca-js PR #269): `$api->pullMobile()`,
sự kiện listener `sync_event`, `$api->getSyncData()`, `Zca\Utils::generateRSAKeyPair()` và
`Zca\Utils::decryptWithPrivateKey()`. Dự án **không** tự viết các phần này nữa, chỉ bọc lại trong
`ZaloApi`/`ZaloListener`.

```php
use Zca\Utils;

// 1. Cặp khoá RSA-2048 dùng cho MỘT lượt đồng bộ.
$keys = Utils::generateRSAKeyPair();
// $keys['publicKeyBase64']  — base64 SPKI TRẦN (đã bỏ header/footer + khoảng trắng) → gửi cho Zalo
// $keys['privateKey']       — PEM PKCS#8 → lưu mã hoá ở zalo_mobile_sync_runs.private_key
// ($keys['privateKeyBase64'], $keys['publicKey'] không dùng; KHÔNG log bất kỳ khoá nào)

// 2. Yêu cầu điện thoại đồng bộ. Phản hồi RỖNG — tiến trình về qua sự kiện `sync_event`.
$api->pullMobile([
    'public_key'  => $keys['publicKeyBase64'],
    'from_seq_id' => $run->from_seq_id,   // con trỏ đã lưu, lần đầu 0
    'is_retry'    => 0,                   // thử lại (4.6.3): 1, CÙNG public key, from_seq_id cũ
    'min_seq_id'  => 0,
    'temp_key'    => '',
]);
// Gói tự thêm pc_name="Web" và imei; gọi GET {file}/api/message/pull_mobile_msg, params mã hoá trên query.
```

- **Gọi `pullMobile` ở đâu:** HTTP đồng bộ nhưng nhanh và hiếm → `MobileSyncJob` gọi từ tiến trình
  queue bằng `ZaloContext::toZcaApi()` (không cần gateway, vì không chờ `file_done`). Sự kiện trả về
  vẫn chỉ đến qua listener của gateway → `zalo:ingest` (4.6.3).
- **Sự kiện `sync_event`:** gateway đăng ký `$api->listener->on('sync_event', …)`, nhận
  `Zca\Models\SyncEvent` gồm `type` (`Zca\Models\SyncEventType::USER_CONFIRM | SYNCMSG_INFO |
  TRANSFER_ERROR | UNKNOWN`), `act`, `act_type` (`"syncmsgmb"`) và `data` — gói đã `json_decode` sẵn khi
  Zalo gửi chuỗi. Gateway chỉ RPUSH, không xử lý gì thêm (2.4):
  `{"type":"event","event":"mobile_sync","account_id","act":$e->act,"data":$e->data}`.
  `UNKNOWN` → vẫn đẩy (consumer log rồi bỏ), để biết khi Zalo thêm `act` mới.
  Hình dạng `data` theo từng loại: xem docblock `src/Models/SyncEvent.php` của gói.
- **Bước 4–5 (4.6.4, 4.6.5) cũng dùng gói:**
  - Tải tệp: `$api->getSyncData([...$syncInfoData, 'returnStream' => true])` → trả
    `['success' => true, 'stream' => ['stream' => PSR-7 StreamInterface, 'metadata' => …, 'response' => …]]`,
    rồi dự án tự chép stream ra tệp tạm theo từng khúc và tự kiểm size + MD5 (4.6.4).
    **KHÔNG** dùng chế độ mặc định (`savePath`): nó đọc **cả tệp vào RAM** (`(string) getBody()`)
    rồi mới ghi, tạo thư mục quyền `0777`, và tên tệp lấy từ `file_name` của Zalo (không theo
    `{accountId}-{runId}` như 4.6.3 yêu cầu).
  - `getSyncData` **không ném lỗi** mà trả `['success' => false, 'error' => …]` → lớp bọc PHẢI kiểm
    `success` và ném `ZaloApiException`; nếu không, lượt đồng bộ chạy tiếp với tệp không tồn tại.
  - Mở gói RSA lấy khoá AES: `Utils::decryptWithPrivateKey($privatePem, $data['encrypted_key'])`
    (RSA-PKCS1, gói đã kiểm đúng 32 byte và ném `ZaloApiError` nếu sai). **Chỉ đến đây là của gói** —
    dẫn xuất khoá, giải mã tệp, ZDB4, XZ (4.6.5 bước 6 → 4.6.8) là mã tự viết.
  - Mã mẫu ở 4.6.4–4.6.5 gọi thẳng `$api->getSyncData`/`Zca\Utils` cho dễ đọc; khi code thật, các lời
    gọi này nằm trong lớp bọc `app/Zalo/Protocol` (0.5), service đồng bộ chỉ gọi lớp bọc.
- **Lưu ý về URL của `pullMobile` (2.1.0):** gói giữ nguyên cách bản vá zca-js gọi `makeURL` hai lần
  (`init()` đã thêm `zpw_ver`/`zpw_type`, `__invoke()` truyền lại hai khoá đó với `apiVersion=false`) →
  URL gửi đi có `zpw_ver`/`zpw_type` **hai lần**. Zalo hiện chấp nhận (worker cũ chạy được với đúng URL
  này). Sửa ở gói nếu muốn gọn, nhưng **không** sửa trong `vendor/` hay vá riêng ở dự án.
- `znoise` (4.6.9) gói **chưa có** → vẫn đăng ký custom API trong `app/Zalo/Protocol/Extensions/ZNoise.php`
  (`$api->custom('znoise', fn(array $p) => …)`, theo khuôn `src/Apis/*.php`: `encodeAES` params →
  `request` → `resolve`; method/tham số đối chiếu `worker/src/zalo/noise-id-resolver.ts`). `custom()` ném
  lỗi khi đăng ký trùng tên trên cùng một `Zca\API` → đăng ký **một lần** lúc tạo API.
- Khoá riêng lưu **mã hoá** (`Crypt::encryptString`) ở bản ghi `zalo_mobile_sync_runs.private_key`,
  xoá (set NULL) ngay khi lượt kết thúc (thành công hay thất bại). Không ghi ra log/đĩa trần.
- Chỉ một lượt cho một tài khoản tại một thời điểm (`Cache::lock("zalo:mobile-sync:{id}", 900)`);
  đang có lượt hoạt động → 409 "Đang có một lượt đồng bộ chạy cho tài khoản này".

#### 4.6.3 Bước 3: máy trạng thái và sự kiện

Gateway nhận sự kiện `sync_event` của zca-php (khung điều khiển `act_type == "syncmsgmb"`,
`act ∈ {user_confirm, syncmsg_info, transfer_error}`, `data` đã giải JSON) → RPUSH
`{"type":"event","event":"mobile_sync","account_id","act","data"}`. Consumer chuyển cho
`ZaloMobileSyncService::handleEvent()`.

```
idle ─start─► waiting_confirm ─user_confirm─► confirmed ─syncmsg_info─► downloading ─► decrypting
                 │  (hạn 120s)                    │ (hạn 360s = 3×120s)                     │
                 └──────── hết hạn ───────────────┴──► error(confirm_timeout|prepare_timeout)│
decrypting ─► importing ─► done
     └─► decrypt_failed (không bóc được ZDB4)          * ─transfer_error─► thử lại / error
```

Quy tắc (mỗi quy tắc đến từ hành vi thật đã gặp):

- **Lọc sự kiện lạc:** bỏ sự kiện khi không có lượt nào đang hoạt động (`waiting_confirm`,
  `confirmed`, `downloading`, `decrypting`, `importing`). Nếu `data.public_key` có mặt và **khác**
  public key của lượt hiện tại → bỏ (log 12 ký tự cuối của hai khoá).
- **Chống xử lý chồng:** Zalo có thể bắn `syncmsg_info` rồi `transfer_error` cách nhau ~100ms cho
  CÙNG một lượt. Đang xử lý `syncmsg_info` (cờ `processing`) thì: `syncmsg_info` thứ hai → bỏ qua;
  `transfer_error` → chỉ log, KHÔNG thử lại chồng. Trong PHP: job `ProcessMobileSyncInfoJob` giữ
  `Cache::lock("zalo:mobile-sync-processing:{id}")`; tệp tạm đặt tên theo `{accountId}-{runId}`
  (không theo accountId trần) để hai lượt không ghi đè nhau.
- **`transfer_error` không phải lỗi:** `error_code == 0` và `error_msg` rỗng → chỉ là báo trạng thái
  từ điện thoại, tiếp tục chờ.
- **Thử lại:** `transfer_error` có `can_retry`, hoặc tải tệp sai size/md5 sau mọi lần tải lại → gửi lại
  yêu cầu với `is_retry=1`, **cùng public key**, `from_seq_id` cũ; tối đa **3** lần, quay về
  `waiting_confirm` (hạn 120s). Hết lượt → `error`.
- **Lần đầu phải là toàn bộ:** `from_seq_id` đã lưu = 0 mà `is_full_transfer != 1` → log cảnh báo
  "dữ liệu có thể thiếu" nhưng VẪN nhập (có còn hơn không). Muốn lấy lại toàn bộ: xoá con trỏ đã lưu.
- `db_info` có thể là chuỗi JSON → `json_decode` an toàn. Lấy `db_info.backup_db.msg_total` và
  `msg_thread` làm **số kỳ vọng** để đối soát cuối lượt.

#### 4.6.4 Bước 4: tải tệp và kiểm tra toàn vẹn

```php
$delays = [0, 1500, 3000, 5000, 8000];   // ms — CDN có thể 404/chưa đủ byte ngay sau syncmsg_info
foreach ($delays as $i => $ms) {
    if ($ms) usleep($ms * 1000);
    @unlink($cryptPath);
    // zca-php getSyncData (kèm cookie phiên) ở chế độ stream; tự chép ra đĩa từng khúc, KHÔNG gom vào RAM:
    // tệp của tài khoản dùng lâu năm có thể vài trăm MB. getSyncData trả success=false thay vì ném lỗi.
    $res = $api->getSyncData([...$info, 'returnStream' => true]);
    if (! ($res['success'] ?? false)) { $fail = 'download_failed'; continue; }
    $in = $res['stream']['stream'];                       // Psr\Http\Message\StreamInterface
    $out = fopen($cryptPath, 'wb');
    while (! $in->eof()) { fwrite($out, $in->read(1 << 20)); }
    fclose($out);
    if ((int) $info['file_size'] > 0 && filesize($cryptPath) !== (int) $info['file_size']) { $fail = 'download_size_mismatch'; continue; }
    $expected = strtolower((string) ($info['checksum_code'] ?? ''));
    if ($expected !== '' && md5_file($cryptPath) !== $expected) { $fail = 'download_checksum_mismatch'; continue; }
    return true;
}
```

#### 4.6.5 Bước 5–6: giải khoá AES và dẫn xuất khoá thật

```php
// Bước 5 — THƯ VIỆN: mở gói RSA. Hệ thống cũ dùng decryptWithPrivateKey của bản vá zca-js;
// zca-php có hàm tương đương 1-1 (RSA-PKCS1 v1.5, base64_decode, kiểm đúng 32 byte).
try {
    $aesKey = \Zca\Utils::decryptWithPrivateKey($privatePem, $info['encrypted_key']);
} catch (\Zca\Errors\ZaloApiError $e) {
    throw new MobileSyncException('rsa_decrypt_failed');
}

// Bước 6 — TỰ VIẾT (zca-php không có): khoá AES thật KHÔNG phải 32 byte nhị phân ở trên, mà là
// 32 KÝ TỰ ĐẦU của chuỗi hex VIẾT HOA của nó (giống cách ứng dụng Zalo PC dùng). Hệ quả: chỉ 16 byte
// đầu của aesKey có tác dụng. Khớp db-crypt.ts:
//   Buffer.from(aesKey.toString('hex').toUpperCase(), 'ascii').subarray(0, 32)
$key = substr(strtoupper(bin2hex($aesKey)), 0, 32);       // 32 byte ASCII → AES-256
```

- Khác biệt không ảnh hưởng: `generateRSAKeyPair()` của zca-js xuất khoá riêng PKCS#1
  (`BEGIN RSA PRIVATE KEY`), của zca-php xuất PKCS#8 (`BEGIN PRIVATE KEY`); `openssl_private_decrypt`
  nhận cả hai. Khoá công khai gửi Zalo giống hệt nhau (base64 DER SPKI).
- PHP chạy với OpenSSL ≥ 3.2 bật *implicit rejection* cho RSA-PKCS1 v1.5: giải bằng sai khoá có thể
  **không báo lỗi** mà trả chuỗi giả. Kiểm 32 byte của gói chặn được phần lớn; phần lọt qua sẽ bị chặn
  ở kiểm `ZDB4.0` (4.6.6) → `decrypt_failed`. Vì vậy log lỗi `decrypt_failed` PHẢI ghi kèm 12 ký tự
  cuối public key của lượt (4.6.3) để phân biệt "sai khoá" với "đổi định dạng".

Đây là điểm mấu chốt đã tốn nhiều công dò: dùng thẳng 32 byte nhị phân làm khoá thì mọi mode đều cho
ra rác.

#### 4.6.6 Bước 7: giải mã từng khối 64 KiB (AES-256-CBC, IV 0, không padding)

Thuật toán (chính xác từng byte):

```
CHUNK = 65536
với mỗi khối [s, e) của tệp, s = 0, 65536, 131072, … ; e = min(len, s + CHUNK):
    encEnd = e - ((e - s) mod 16)               // phần chia hết cho 16
    out[s, encEnd)  = AES-256-CBC-Decrypt(key, IV = 16 byte 0x00, padding = TẮT)(in[s, encEnd))
    out[encEnd, e)  = in[encEnd, e)             // đuôi lẻ < 16 byte: CHÉP NGUYÊN, không giải mã
```

**IV reset về 0 ở đầu MỖI khối 64 KiB** — đây là chỗ dễ sai nhất: giải mã liên tục cả tệp thì 64 KiB
đầu vẫn đúng (header vẫn ra `ZDB4.0`) nhưng phần sau hỏng, XZ báo `Compressed data is corrupt` với tệp
lớn. Tệp nhỏ (< 64 KiB) chạy đúng cả hai cách nên lỗi này chỉ lộ ra ở tài khoản có nhiều dữ liệu.

Mã PHP: `ZaloDbCryptDecoder::decryptToFile()` trong lớp hoàn chỉnh ở **4.6.8a**.

**Đường dự phòng chẩn đoán** (không bắt buộc port): nếu không ra `ZDB4.0`, bản Node thử thêm ma trận
AES-256 {CBC, CTR, CFB, OFB} × IV {16 byte 0, 16 byte đầu tệp (bỏ khỏi thân), key[0..16], key[16..32],
md5(key)} × padding {bật, tắt}, rồi ECB, rồi GCM (IV 12 byte, tag = 16 byte cuối), với khoá 32 byte nhị
phân; chấp nhận khi kết quả bắt đầu bằng `SQLite format 3\0` hoặc gzip (`1f 8b`) bọc SQLite. Không tổ
hợp nào khớp → ghi 5 tổ hợp có entropy Shannon thấp nhất (trên 64 KiB đầu) vào log để điều tra, chuyển
`decrypt_failed`. Trên dữ liệu thật hiện tại chỉ nhánh ZDB4 là đúng.

Hệ thống cũ còn hai nhánh **KHÔNG port**:
- `decodeWithNativeBridge` (`worker/src/zalo/native-decoder-client.ts` + `tools/zalo-native-decoder-server.cjs`):
  gọi sidecar chạy Zalo Electron trên máy macOS (`MOBILE_SYNC_NATIVE_DECODER_URL`). Chỉ là công cụ dò
  định dạng lúc đầu; không chạy được trên Linux/Docker.
- `saveFailedArtifacts` (bật bằng `MOBILE_SYNC_KEEP_FAILED_ARTIFACTS`): khi giải mã thất bại, chép tệp
  `.db.crypt` **kèm `private_key_pem` và `aes_key_hex` dạng trần** ra đĩa để dò tay. Trái quy tắc ở 4.6.2
  (khoá riêng không ra đĩa trần). Nếu cần giữ để điều tra: chỉ giữ tệp `.db.crypt` + `encrypted_key` +
  chẩn đoán; khoá riêng giữ mã hoá trong `zalo_mobile_sync_runs` và chỉ admin xuất được, có hạn.

#### 4.6.7 Bước 8: bố cục container ZDB4 (mọi số nguyên là uint32 **big-endian**)

```
offset  độ dài   trường
0       6        magic = "ZDB4.0" (ASCII)
6       4        hashEnd       — offset (tính từ đầu container) nơi KẾT THÚC vùng dữ liệu được băm
10      4        xxh32         — XXH32(seed 0) của container[14 .. hashEnd)
14      4        fileCount     — số tệp SQLite (0..10000)
18      …        lặp fileCount lần:
                   4        nameLen  (1..128)
                   nameLen  name     (UTF-8, chỉ là tên tệp, không có "/" — kiểm basename(name) === name)
                   4        size     (byte sau giải nén, 0..2.000.000.000)
X       …        luồng XZ, bắt đầu bằng magic FD 37 7A 58 5A 00, kéo dài tới hashEnd
hashEnd …        (phần sau hashEnd bỏ qua)
```

Kiểm tra hợp lệ (sai bất kỳ điều nào → `decrypt_failed`): độ dài ≥ 18; `14 < hashEnd ≤ len`;
`fileCount ≤ 10000`; mỗi entry nằm trọn trước `hashEnd`; tại offset X phải đúng magic XZ.
**XXH32 chỉ dùng chẩn đoán, KHÔNG làm hỏng lượt** khi lệch (ứng dụng Zalo PC vẫn chấp nhận một số tệp
lớn có checksum lệch; XZ + SQLite mới là phép kiểm thật). PHP ≥ 8.1 có sẵn:
`hash('xxh32', $payload) === sprintf('%08x', $xxh32)` — đọc payload theo luồng bằng `hash_init('xxh32')`
+ `hash_update_stream` để không nạp cả tệp vào RAM.

Mã PHP: `ZaloDbCryptDecoder::parseHeader()` và `verifyChecksum()` ở **4.6.8a**.

#### 4.6.8 Bước 9: giải nén XZ theo luồng và cắt ra từng SQLite

Tổng SQLite sau giải nén có thể vài trăm MB → KHÔNG nạp vào RAM:

1. Chép đoạn `[xz_offset, xz_end)` của container ra tệp `{run}.xz` (`stream_copy_to_stream($in, $out,
   $length, $offset)`). Xoá container ngay sau đó.
2. `proc_open(['xzcat', $xzPath], [1 => ['pipe','w'], 2 => ['pipe','w']], $pipes)` — truyền tệp làm đối số
   thay vì ghi vào stdin, để tránh deadlock đọc/ghi cùng lúc.
3. Đọc stdout từng khối 1 MiB; giữ con trỏ `(entryIndex, writtenInEntry)`: ghi vào tệp
   `{run}-zdb-{index}-{name}` (quyền 0600, thư mục 0700) cho tới khi đủ `size` của entry thì đóng tệp
   (kèm md5) và sang entry kế. Entry `size = 0` → tạo tệp rỗng rồi sang ngay — **kể cả khi luồng XZ đã
   hết**. (Bản TS `xzDecompressToFiles` chỉ mở entry kế khi còn dữ liệu, nên entry rỗng nằm ở CUỐI danh
   sách làm nó báo nhầm "XZ kết thúc sớm". Bản PHP sửa điểm này; test 4.6.14 PHẢI có ca entry rỗng ở cuối.)
4. Còn dữ liệu sau khi đã đủ mọi entry → lỗi "dữ liệu XZ còn dư". Hết luồng mà chưa đủ entry → lỗi
   "XZ kết thúc sớm: mới ghi i/N DB". Mã thoát `xzcat` khác 0 → lỗi kèm stderr. Lỗi bất kỳ → xoá mọi
   tệp đã ghi.
5. Máy chủ PHẢI có binary `xz` (Debian: `apt-get install xz-utils`; Alpine: `apk add xz`). Kiểm tra lúc
   khởi động: `command -v xzcat`.

#### 4.6.8a Mã PHP hoàn chỉnh cho bước 6 → 9 (chép nguyên vào dự án)

Bản PHP của nhánh ZDB4 trong `worker/src/zalo/db-crypt.ts` (khoá → AES theo khối → header ZDB4 →
XZ → từng SQLite). zca-php **không** có phần này. Đặt tại
`app/Zalo/MobileSync/ZaloDbCryptDecoder.php` (tách `MobileSyncException` ra tệp riêng theo PSR-4).
Lớp không phụ thuộc Laravel hay zca-php → unit test thuần được.

**Đã kiểm chứng chéo với bản TS gốc** (03/11/2026, PHP 8.4, xz-utils): cùng một tệp `.db.crypt`
dựng bằng bộ sinh ở 4.6.14, `decodeDbCryptToDirectory()` của TS và `decode()` của PHP ra **cùng md5
từng SQLite**, và `parseZdb4Container` của TS xác nhận checksum XXH32 khớp với `verifyChecksum()`.

| Ca | TS gốc | PHP |
|---|---|---|
| 6 entry (40 KB … 3 MB), entry rỗng ở giữa, rác sau `hashEnd` | đúng | đúng, md5 trùng TS |
| 1 entry < 64 KiB | đúng | đúng |
| entry rỗng ở **cuối** | trả `null` (lỗi đã nêu ở 4.6.8) | đúng |
| sai khoá | — | `decrypt_failed` |
| 120 MB, 3 entry | — | đúng, 0,5 s, RSS tối đa ~38 MB |
| XZ hỏng giữa luồng | — | `xz_failed`, không sót tệp nào |
| thiếu binary `xzcat` | — | `xz_failed`, không sót tệp nào |
| giải liên tục không reset IV | — | header vẫn ra `ZDB4.0` nhưng phần sau sai (đúng như cảnh báo 4.6.6) |

Chưa kiểm được trên tệp `.db.crypt` thật của Zalo (cần tài khoản phụ, Phase 4) — đó là cổng nghiệm thu F16.

Cách dùng trong job (sau bước 4–5 ở 4.6.4–4.6.5):

```php
$decoder = new ZaloDbCryptDecoder();
try {
    $dbs = $decoder->decode($cryptPath, $aesKey, storage_path('app/zalo-sync'), "{$accountId}-{$runId}");
    // $dbs: [['name' => 'msg_…', 'path' => '…', 'size' => …, 'md5' => '…'], …] → bước 10–12 (4.6.9 →)
} catch (MobileSyncException $e) {
    if ($e->reason === 'decrypt_failed') {
        Log::warning('Không giải mã được tệp đồng bộ', ['diagnose' => $decoder->diagnose($cryptPath, $aesKey)]);
    }
    $run->fail($e->reason, $e->getMessage());   // KHÔNG log $aesKey / khoá riêng
} finally {
    @unlink($cryptPath);
}
```

`decode()` không ném lỗi khi XXH32 lệch (chỉ chẩn đoán, 4.6.7). Muốn log cảnh báo thì gọi riêng
`decryptToFile()` → `parseHeader()` → `verifyChecksum()` → `extractDatabases()` như bên trong `decode()`.

```php
<?php

declare(strict_types=1);

namespace App\Zalo\MobileSync;

/**
 * Lỗi của pipeline giải mã. $reason là mã máy đọc được, ghi vào zalo_mobile_sync_runs.error_reason.
 */
final class MobileSyncException extends \RuntimeException
{
    public function __construct(public readonly string $reason, string $message = '')
    {
        parent::__construct($message !== '' ? $message : $reason);
    }
}

/**
 * Giải mã tệp `.db.crypt` của luồng pull_mobile_msg ra các tệp SQLite ChatContent (bước 6 → 9).
 *
 * Bản PHP của worker/src/zalo/db-crypt.ts (nhánh ZDB4 — nhánh duy nhất đúng trên dữ liệu thật).
 * Mọi bước chạy theo luồng trên đĩa, RAM gần như cố định dù tệp vài trăm MB: không bao giờ
 * nạp cả tệp mã hoá, container hay dữ liệu đã giải nén vào bộ nhớ.
 */
final class ZaloDbCryptDecoder
{
    /** IV reset về 0 ở đầu MỖI khối này — giải liên tục cả tệp thì chỉ 64 KiB đầu đúng. */
    private const CHUNK = 65536;
    private const ZDB4_MAGIC = 'ZDB4.0';
    private const XZ_MAGIC = "\xFD7zXZ\x00";
    /** 10000 entry × (4 + 128 + 4) + 18 + 6 byte < 1,4 MB: header luôn nằm trọn trong 2 MiB đầu. */
    private const HEADER_READ = 2 * 1024 * 1024;
    private const MAX_FILES = 10000;
    private const MAX_NAME_LEN = 0x80;
    private const MAX_ENTRY_SIZE = 2_000_000_000;
    private const IO_BLOCK = 1024 * 1024;

    public function __construct(private readonly string $xzcatBinary = 'xzcat')
    {
    }

    /**
     * Chạy trọn bước 6 → 9. Tệp trung gian (.zdb, .xz) luôn bị xoá, kể cả khi lỗi.
     *
     * @param string $aesKey 32 byte nhị phân mở từ RSA (Zca\Utils::decryptWithPrivateKey)
     * @param string $prefix nên là "{accountId}-{runId}" để hai lượt không ghi đè nhau (4.6.3)
     * @return list<array{name: string, path: string, size: int, md5: string}>
     */
    public function decode(string $cryptPath, string $aesKey, string $workDir, string $prefix): array
    {
        if (! is_dir($workDir) && ! mkdir($workDir, 0700, true) && ! is_dir($workDir)) {
            throw new MobileSyncException('workdir_failed', "Không tạo được thư mục tạm {$workDir}");
        }

        $zdbPath = "{$workDir}/{$prefix}.zdb";
        $xzPath = "{$workDir}/{$prefix}.xz";

        try {
            $this->decryptToFile($cryptPath, self::deriveKey($aesKey), $zdbPath);
            $header = $this->parseHeader($zdbPath);
            $header['checksum_ok'] = $this->verifyChecksum($zdbPath, $header);
            $this->copyRange($zdbPath, $xzPath, $header['xz_offset'], $header['xz_end'] - $header['xz_offset']);
            @unlink($zdbPath);   // container không cần nữa — giải phóng đĩa sớm

            return $this->extractDatabases($xzPath, $header['entries'], $workDir, "{$prefix}-zdb");
        } finally {
            @unlink($zdbPath);
            @unlink($xzPath);
        }
    }

    /**
     * Bước 6: khoá AES thật là 32 KÝ TỰ ĐẦU của hex VIẾT HOA của khoá RSA mở ra (như Zalo PC),
     * không phải 32 byte nhị phân. Hệ quả: chỉ 16 byte đầu của $aesKey có tác dụng.
     */
    public static function deriveKey(string $aesKey): string
    {
        if (strlen($aesKey) !== 32) {
            throw new MobileSyncException('bad_aes_key', 'Khoá AES dài ' . strlen($aesKey) . ' byte, cần đúng 32 byte');
        }

        return substr(strtoupper(bin2hex($aesKey)), 0, 32);
    }

    /**
     * Bước 7: AES-256-CBC, IV 16 byte 0, KHÔNG padding, reset IV ở đầu mỗi khối 64 KiB;
     * đuôi lẻ < 16 byte của khối cuối chép nguyên. Kết quả phải bắt đầu bằng "ZDB4.0".
     */
    public function decryptToFile(string $cryptPath, string $key, string $outPath): void
    {
        $in = $this->open($cryptPath, 'rb');
        $out = $this->open($outPath, 'wb');
        @chmod($outPath, 0600);
        $iv = str_repeat("\0", 16);

        try {
            while (($chunk = $this->readExactly($in, self::CHUNK)) !== '') {
                $len = strlen($chunk);
                $encLen = $len - ($len % 16);
                $plain = '';
                if ($encLen > 0) {
                    // OPENSSL_ZERO_PADDING khi giải mã = không kiểm/bỏ padding (tương đương setAutoPadding(false)).
                    $plain = openssl_decrypt(substr($chunk, 0, $encLen), 'aes-256-cbc', $key, OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING, $iv);
                    if ($plain === false) {
                        throw new MobileSyncException('aes_failed', 'openssl_decrypt lỗi: ' . (openssl_error_string() ?: 'không rõ'));
                    }
                }
                $this->write($out, $plain . substr($chunk, $encLen));
            }
        } finally {
            fclose($in);
            fclose($out);
        }

        if (file_get_contents($outPath, false, null, 0, strlen(self::ZDB4_MAGIC)) !== self::ZDB4_MAGIC) {
            throw new MobileSyncException('decrypt_failed', 'Giải mã xong nhưng không ra container ZDB4.0 (sai khoá hoặc Zalo đổi định dạng)');
        }
    }

    /**
     * Bước 8: header ZDB4, mọi số nguyên uint32 big-endian.
     *
     * @return array{entries: list<array{name: string, size: int}>, xz_offset: int, xz_end: int, xxh32: int}
     */
    public function parseHeader(string $zdbPath): array
    {
        $len = filesize($zdbPath);
        $fh = $this->open($zdbPath, 'rb');
        $head = $this->readExactly($fh, self::HEADER_READ);
        fclose($fh);

        $u32 = static fn (int $o): int => $o >= 0 && $o + 4 <= strlen($head) ? unpack('N', $head, $o)[1] : -1;

        if ($len < 18 || ! str_starts_with($head, self::ZDB4_MAGIC)) {
            throw new MobileSyncException('zdb4_bad_magic');
        }

        $hashEnd = $u32(6);
        $xxh32 = $u32(10);
        $count = $u32(14);
        if ($hashEnd <= 14 || $hashEnd > $len || $count < 0 || $count > self::MAX_FILES) {
            throw new MobileSyncException('zdb4_bad_header', "hashEnd={$hashEnd} fileCount={$count} len={$len}");
        }

        $o = 18;
        $entries = [];
        for ($i = 0; $i < $count; $i++) {
            $nameLen = $u32($o);
            $o += 4;
            if ($nameLen < 1 || $nameLen > self::MAX_NAME_LEN || $o + $nameLen + 4 > $hashEnd) {
                throw new MobileSyncException('zdb4_bad_entry', "entry {$i}: nameLen={$nameLen}");
            }
            $name = substr($head, $o, $nameLen);
            $o += $nameLen;
            $size = $u32($o);
            $o += 4;
            // basename chặn path traversal: tên lấy từ dữ liệu ngoài và được ghép vào đường dẫn ở bước 9.
            if (! mb_check_encoding($name, 'UTF-8') || basename($name) !== $name || $size < 0 || $size > self::MAX_ENTRY_SIZE) {
                throw new MobileSyncException('zdb4_bad_entry', "entry {$i}: size={$size}");
            }
            $entries[] = ['name' => $name, 'size' => $size];
        }

        if (substr($head, $o, strlen(self::XZ_MAGIC)) !== self::XZ_MAGIC) {
            throw new MobileSyncException('zdb4_no_xz', "Không thấy magic XZ tại offset {$o}");
        }

        return ['entries' => $entries, 'xz_offset' => $o, 'xz_end' => $hashEnd, 'xxh32' => $xxh32];
    }

    /**
     * XXH32 (seed 0) của container[14 .. hashEnd). CHỈ để chẩn đoán: Zalo PC vẫn nhận một số tệp lớn
     * lệch checksum, XZ + SQLite mới là phép kiểm thật → lệch thì log cảnh báo, KHÔNG làm hỏng lượt.
     */
    public function verifyChecksum(string $zdbPath, array $header): bool
    {
        $fh = $this->open($zdbPath, 'rb');
        try {
            fseek($fh, 14);
            $ctx = hash_init('xxh32');
            hash_update_stream($ctx, $fh, $header['xz_end'] - 14);
        } finally {
            fclose($fh);
        }

        return hash_final($ctx) === sprintf('%08x', $header['xxh32']);
    }

    /**
     * Bước 9: giải nén luồng XZ bằng xzcat và cắt ra từng tệp SQLite theo `size` của entry.
     *
     * @param list<array{name: string, size: int}> $entries
     * @return list<array{name: string, path: string, size: int, md5: string}>
     */
    public function extractDatabases(string $xzPath, array $entries, string $workDir, string $filePrefix): array
    {
        // Truyền tệp làm đối số thay vì ghi stdin: không phải vừa ghi vừa đọc pipe (tránh deadlock).
        $proc = @proc_open([$this->xzcatBinary, '--', $xzPath], [1 => ['pipe', 'w'], 2 => ['pipe', 'w']], $pipes);
        if (! is_resource($proc)) {
            throw new MobileSyncException('xz_failed', "Không chạy được {$this->xzcatBinary} (cần gói xz-utils)");
        }

        $databases = [];
        $index = 0;
        $written = 0;
        $fh = null;
        $hash = null;

        $open = function () use (&$fh, &$hash, &$index, $entries, $workDir, $filePrefix): void {
            $path = "{$workDir}/{$filePrefix}-{$index}-{$entries[$index]['name']}";
            $fh = $this->open($path, 'wb');
            @chmod($path, 0600);
            $hash = hash_init('md5');
        };
        $close = function () use (&$fh, &$hash, &$index, &$written, &$databases, $entries, $workDir, $filePrefix): void {
            fclose($fh);
            $databases[] = [
                'name' => $entries[$index]['name'],
                'path' => "{$workDir}/{$filePrefix}-{$index}-{$entries[$index]['name']}",
                'size' => $entries[$index]['size'],
                'md5' => hash_final($hash),
            ];
            $fh = null;
            $hash = null;
            $written = 0;
            $index++;
        };
        // Entry size 0 không cần byte nào: đóng ngay, KỂ CẢ khi luồng đã hết (bản TS báo nhầm "XZ kết thúc sớm").
        $skipEmpty = function () use (&$index, $entries, $open, $close): void {
            while ($index < count($entries) && $entries[$index]['size'] === 0) {
                $open();
                $close();
            }
        };

        try {
            $skipEmpty();
            while (! feof($pipes[1])) {
                $chunk = fread($pipes[1], self::IO_BLOCK);
                if ($chunk === false || $chunk === '') {
                    continue;
                }
                $offset = 0;
                $chunkLen = strlen($chunk);
                while ($offset < $chunkLen) {
                    if ($index >= count($entries)) {
                        throw new MobileSyncException('xz_trailing_data', 'Dữ liệu XZ còn dư sau khi đã ghi đủ danh sách DB ZDB4');
                    }
                    if ($fh === null) {
                        $open();
                    }
                    $take = min($entries[$index]['size'] - $written, $chunkLen - $offset);
                    $slice = substr($chunk, $offset, $take);
                    $this->write($fh, $slice);
                    hash_update($hash, $slice);
                    $written += $take;
                    $offset += $take;
                    if ($written === $entries[$index]['size']) {
                        $close();
                        $skipEmpty();
                    }
                }
            }

            $stderr = trim((string) stream_get_contents($pipes[2]));
            fclose($pipes[1]);
            fclose($pipes[2]);
            $exit = proc_close($proc);
            $proc = null;

            if ($exit !== 0) {
                throw new MobileSyncException('xz_failed', "xzcat giải nén ZDB4 thất bại (exit {$exit})" . ($stderr !== '' ? ": {$stderr}" : ''));
            }
            if ($index !== count($entries)) {
                throw new MobileSyncException('xz_truncated', "XZ kết thúc sớm: mới ghi {$index}/" . count($entries) . ' DB');
            }

            return $databases;
        } catch (\Throwable $e) {
            if (is_resource($fh)) {
                fclose($fh);
            }
            if ($proc !== null) {
                @fclose($pipes[1]);
                @fclose($pipes[2]);
                proc_terminate($proc);
                proc_close($proc);
            }
            // Lỗi bất kỳ → xoá mọi tệp đã ghi, kể cả tệp đang ghi dở.
            foreach ($databases as $db) {
                @unlink($db['path']);
            }
            if ($index < count($entries)) {
                @unlink("{$workDir}/{$filePrefix}-{$index}-{$entries[$index]['name']}");
            }
            throw $e;
        }
    }

    /**
     * Chẩn đoán khi không ra ZDB4.0 (không bắt buộc): 5 tổ hợp AES {CBC, CTR, CFB, OFB} × IV, khoá
     * 32 byte nhị phân, có entropy Shannon thấp nhất trên 64 KiB đầu → ghi log để dò định dạng mới.
     *
     * @return list<array{label: string, entropy: float, head_hex: string}>
     */
    public function diagnose(string $cryptPath, string $aesKey): array
    {
        $fh = $this->open($cryptPath, 'rb');
        $head = $this->readExactly($fh, self::CHUNK + 16);   // đầu ra 64 KiB đầu chỉ phụ thuộc chừng này byte vào
        fclose($fh);

        $ivs = [
            'zeros(16)' => [str_repeat("\0", 16), 0],
            'file[0..16] (prefix)' => [substr($head, 0, 16), 16],
            'key[0..16]' => [substr($aesKey, 0, 16), 0],
            'key[16..32]' => [substr($aesKey, 16, 16), 0],
            'md5(key)' => [md5($aesKey, true), 0],
        ];

        $candidates = [];
        foreach (['aes-256-cbc', 'aes-256-ctr', 'aes-256-cfb', 'aes-256-ofb'] as $mode) {
            foreach ($ivs as $label => [$iv, $skip]) {
                $body = substr($head, $skip, self::CHUNK);
                $body = substr($body, 0, strlen($body) - strlen($body) % 16);
                $out = openssl_decrypt($body, $mode, $aesKey, OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING, $iv);
                if ($out === false || $out === '') {
                    continue;
                }
                $candidates[] = ['label' => "{$mode} iv={$label}", 'entropy' => self::entropy($out), 'head_hex' => bin2hex(substr($out, 0, 16))];
            }
        }
        usort($candidates, static fn (array $a, array $b): int => $a['entropy'] <=> $b['entropy']);

        return array_slice($candidates, 0, 5);
    }

    private static function entropy(string $buf): float
    {
        $n = min(strlen($buf), self::CHUNK);
        $h = 0.0;
        foreach (count_chars(substr($buf, 0, $n), 1) as $f) {
            $p = $f / $n;
            $h -= $p * log($p, 2);
        }

        return $h;
    }

    /** Chép [offset, offset+length) của $src sang $dst theo luồng. */
    private function copyRange(string $src, string $dst, int $offset, int $length): void
    {
        $in = $this->open($src, 'rb');
        $out = $this->open($dst, 'wb');
        @chmod($dst, 0600);
        try {
            $copied = stream_copy_to_stream($in, $out, $length, $offset);
        } finally {
            fclose($in);
            fclose($out);
        }
        if ($copied !== $length) {
            throw new MobileSyncException('zdb4_truncated', "Chép vùng XZ được {$copied}/{$length} byte");
        }
    }

    /** fread có thể trả ít hơn yêu cầu; khối PHẢI đủ 64 KiB (trừ khối cuối) để ranh giới reset IV đúng. */
    private function readExactly($fh, int $n): string
    {
        $buf = '';
        while (strlen($buf) < $n && ! feof($fh)) {
            $part = fread($fh, $n - strlen($buf));
            if ($part === false || $part === '') {
                break;
            }
            $buf .= $part;
        }

        return $buf;
    }

    /** @return resource */
    private function open(string $path, string $mode)
    {
        $fh = @fopen($path, $mode);
        if ($fh === false) {
            throw new MobileSyncException('io_failed', "Không mở được {$path}");
        }

        return $fh;
    }

    private function write($fh, string $data): void
    {
        if ($data !== '' && fwrite($fh, $data) !== strlen($data)) {
            throw new MobileSyncException('io_failed', 'Ghi tệp tạm thất bại (đầy đĩa?)');
        }
    }
}
```

#### 4.6.9 Bước 10: tên tệp → thread, và map plain id → noise id

```
base = name bỏ đuôi ".db" (không phân biệt hoa thường), bỏ tiền tố "out-"
"group_<id>"     → group, plain_id = <id>
"g<chữ số>"      → group, plain_id = phần số
còn lại          → user,  plain_id = dãy chữ số CUỐI của base (không có thì cả base)
```

Id trong tệp sao lưu là **plain id**, còn id hệ thống nhận qua WebSocket là **noise id** (id đã làm
nhiễu theo từng tài khoản). Không map thì hội thoại nhập về sẽ nằm ở `thread_id` khác, không khớp với hội
thoại realtime và hiện toàn số lạ. Cách map:

- Gom mọi plain id (bỏ tiền tố `g`, chỉ giữ chuỗi toàn chữ số, khử trùng), chia khối tối đa **5000 id**
  (user điền trước, group lấp phần còn lại).
- Gọi API Zalo `POST https://zwid.api.zalo.me/api/znoise` qua `ZaloApi` (custom API `znoise` — zca-php
  chưa có, cách đăng ký ở cuối 4.6.2) với tham số
  `{"fids":[int…], "gids":[int…]}` (bỏ khoá rỗng). Phản hồi `{fids:[…], gids:[…]}` **cùng thứ tự** với
  mảng gửi đi → ghép cặp theo chỉ số, `min(len)` phần tử. Noise id của group có thể có tiền tố `g` → bỏ.
- Lỗi/rỗng → log cảnh báo, dùng plain id (dữ liệu vẫn vào nhưng có thể không khớp hội thoại realtime).

#### 4.6.10 Bước 11: đọc SQLite `ChatContent`

```php
$pdo = new PDO('sqlite:' . $dbPath, null, null, [PDO::SQLITE_ATTR_OPEN_FLAGS => PDO::SQLITE_OPEN_READONLY]);
// Không có bảng ChatContent → bỏ tệp này (log).
$rows = $pdo->query(
    'SELECT SenderId, CliMsgId, GlbMsgId, MsgStatus, MsgType, TimeStamp, TTL, MsgContent, RefCliMsgId, BinNet
       FROM ChatContent
      WHERE MsgStatus > 0 AND CliMsgId IS NOT NULL
      ORDER BY TimeStamp ASC, CliMsgId ASC'
);   // duyệt bằng fetch() từng dòng, gom lô 500 — không fetchAll() (thread lớn hàng chục nghìn dòng)
```

**Chiều tin (direction)** — thuật toán:

```
plainThread = plain_id của tệp; senders = tập SenderId khác rỗng trong tệp
mapSender(s):
    nếu idMap[s] có                         → idMap[s]                (noise id)
    nếu thread là user và s == plainThread  → thread.id (noise)
    nếu thread là user và s != plainThread và biết ownId → ownId
    còn lại                                 → s
direction(s):
    nếu biết ownId và mapSender(s) == ownId → 'out'
    nếu thread là user, |senders| > 1, plainThread ∈ senders → (s == plainThread ? 'in' : 'out')
    nếu thread là user, |senders| == 1, s != plainThread     → 'out'
    còn lại                                 → 'in'
```

(Trong sao lưu 1-1, tên tệp là plain id của người đối thoại, nên người gửi khác id đó thường chính là
tài khoản đang khôi phục. Với nhóm không có map chắc chắn plain → own, nên mặc định `in` trừ khi map ra ownId.)

**Ánh xạ cột → NormalizedMessage:**

| Trường | Giá trị |
|---|---|
| `msg_id` | `GlbMsgId` nếu ≠ `0`; ngược lại `"sync:{thread.id}:{CliMsgId}"` |
| `cli_msg_id` | `CliMsgId` |
| `thread_id` / `thread_type` | noise id của tệp / `user`\|`group` |
| `sender_id` | `mapSender(SenderId)` |
| `sender_name` | rỗng → bổ sung sau (thứ tự: thông tin trong dòng/BinNet → tên mention → `zalo_contacts`/tra hồ sơ → cuối cùng mới là id) |
| `content` | `MsgContent ?? ''` |
| `msg_type` | bảng dưới |
| `attachments` | từ BinNet (4.6.11) |
| `sent_at` | `TimeStamp`; nếu < 10.000.000.000 thì là giây → ×1000; ≤ 0/không hợp lệ → thời điểm hiện tại |
| `quote_msg_id` | `RefCliMsgId` ≠ 0 → `"sync:{thread.id}:{RefCliMsgId}"` (chỉ khớp được tin gốc nếu tin gốc cũng không có GlbMsgId — giới hạn đã biết) |
| `quote_payload` | `{content: MsgContent, msgType, uidFrom: sender_id, msgId, cliMsgId, ts: TimeStamp (chuỗi), ttl: TTL (số)}` |
| `quote_preview`, `mentions` | `null`, `[]` |
| `is_backfill` | `true` |

Bảng `MsgType` (số) → `msg_type`: `0 webchat`, `2 chat.doodle`, `3/4/31 chat.photo`, `6 chat.voice`,
`10 chat.sticker`, `12 chat.recommended`, `15 chat.list.action`, `18 chat.location.new`,
`19 chat.video.msg`, `22 share.file`, `23 chat.gif`, `24 chat.webcontent`, `33 chat.delete`,
`36 chat.undo`, `53 chat.webcontent.v2`; số khác giữ nguyên dạng chuỗi.

#### 4.6.11 Định dạng BinNet (đính kèm) — TLV big-endian

Cột `BinNet` (BLOB) là chuỗi TLV: `tag uint32 BE` + `length uint32 BE` + `value[length]`, nối liền.
Một vùng TLV chỉ hợp lệ khi đọc **vừa khít** tới cuối (thừa/thiếu byte → coi như không parse được,
trả rỗng); `length > 20.000.000` → không hợp lệ.

```
cấp ngoài:  tag 5 = property (TLV con)      tag 6 = attach (TLV con, có thể lặp nhiều lần)
property:   30 size(int32)  31 subType(int32)  32 type(int32)  33 ext(utf8)
attach:     40 type(utf8)   41 catId(int32)    42 id(int32)    43 title(utf8)   44 childNumber(int32)
            45 name(utf8)   46 params(utf8)    47 fileName(utf8) 48 href(utf8)  49 thumb(utf8)
            50 description(utf8)  66 remains(utf8)  67 extra(utf8)  68 raw(utf8)
int32: đúng 4 byte, có dấu, big-endian; độ dài khác 4 → null
```

```php
private function readTlv(string $buf, int $start, int $end): array
{
    $items = []; $o = $start;
    while ($o + 8 <= $end) {
        ['t' => $tag, 'l' => $len] = unpack('Nt/Nl', substr($buf, $o, 8));
        $next = $o + 8 + $len;
        if ($len > 20_000_000 || $next > $end) return [];
        $items[] = [$tag, substr($buf, $o + 8, $len)];
        $o = $next;
    }
    return $o === $end ? $items : [];
}
private function int32(string $v): ?int
{
    if (strlen($v) !== 4) return null;
    $n = unpack('N', $v)[1];
    return $n >= 0x80000000 ? $n - 0x100000000 : $n;
}
```

Dựng `attachments[]` từ các attach (theo `MsgType` của dòng):

- `MsgType = 10` (sticker) và attach có `id` nguyên dương → `{type:"sticker", sticker_id:id, url:"", thumb_url:null}`
  (URL ảnh tra sau như 5.5).
- Còn lại: `url = href`, `thumb_url = thumb`, `name = title ?: name ?: fileName`; cả ba rỗng → bỏ attach.
  `type`: MsgType 3/4/31 → `image`; 19 → `video`; 6 → `audio`; 10 → `sticker`; khác → `file`.
  URL ảnh cũ có thể có đuôi `.jxl` — giữ nguyên, giao diện hiển thị được trên trình duyệt hỗ trợ, nếu
  không thì rơi về liên kết.

#### 4.6.12 Bước 12: ghi DB, con trỏ, dọn dẹp

- Ghi **trực tiếp** từ job qua `ZaloMessageIngestService::ingest()` theo lô 500 tin (đồng bộ → tự có
  backpressure). KHÔNG RPUSH hàng trăm nghìn tin vào `zalo:ingest` (bản Node từng làm tràn hàng đợi 10k
  và mất 326k tin). Tin realtime vẫn đi đường nhanh riêng, không bị lượt nhập lớn làm chậm.
- Chống trùng nhờ `UNIQUE(zalo_account_id, msg_id)` — chạy lại lượt đồng bộ là an toàn. Không chống
  trùng bằng nội dung + thời gian (tin giống hệt nhau trong nhóm là bình thường).
- `is_backfill=true` → không auto-reply, không thắp chưa đọc cho hội thoại chưa mở (5.7).
- Xong từng SQLite → xoá ngay tệp đó. Xong cả lượt → lưu `from_seq_id` (của `syncmsg_info`),
  `last_synced_at`, `imported` vào `zalo_mobile_sync_runs` / cột `zalo_accounts.mobile_sync_seq_id`
  **SAU KHI** lô cuối đã ghi xong (lưu sớm mà job chết giữa chừng thì lần sau tưởng đã đủ). Mất con trỏ
  không mất tin, chỉ khiến lần sau xin lại toàn bộ.
- `finally`: xoá `.db.crypt`, container, `.xz`, mọi `.db`; xoá khoá riêng (trừ khi đang quay lại
  `waiting_confirm` để thử lại — lượt thử lại dùng cùng cặp khoá).
- Chỉ ở môi trường dev/staging mới bật `MOBILE_SYNC_KEEP_FAILED_ARTIFACTS=true` để giữ tệp lỗi
  (`.db.crypt` + JSON gồm `aes_key_hex`, `db_info`, chẩn đoán) — tệp này chứa toàn bộ lịch sử chat.

#### 4.6.13 Đối soát và UI

- Cuối lượt: `imported ≈ db_info.backup_db.msg_total`, `số tệp SQLite ≈ msg_thread`; lệch nhiều →
  hiện cảnh báo trong kết quả (không coi là lỗi).
- `GET /api/zalo-accounts/{id}/sync-mobile` trả `{status, detail}`; UI poll 2 giây/lần, hiển thị:

| Trạng thái | Nội dung modal |
|---|---|
| `waiting_confirm` | "Mở Zalo trên điện thoại và bấm **Đồng ý** để đồng bộ tin nhắn" + đếm ngược 120s |
| `confirmed` | "Điện thoại đã đồng ý. Zalo đang chuẩn bị dữ liệu…" (có thể vài phút) |
| `downloading` | "Đang tải dữ liệu ({file_size} MB)…" |
| `decrypting` | "Đang giải mã dữ liệu…" |
| `importing` | "Đang nhập {imported}/{msg_total} tin ({database_count} hội thoại)…" |
| `done` | "Đã nhập {imported} tin từ {n} hội thoại." + nút Đóng (danh sách hội thoại tự tải lại) |
| `error` | câu theo `reason`: `confirm_timeout` "Chưa nhận được xác nhận từ điện thoại" · `prepare_timeout` "Zalo chuẩn bị dữ liệu quá lâu" · `transfer_error` "Điện thoại báo lỗi: {error_msg}" · `download_*` "Tải dữ liệu không trọn vẹn" · `rsa_decrypt_failed` "Không giải được khoá dữ liệu" · `processing_error` "Lỗi khi nhập dữ liệu" — kèm nút **Thử lại** |
| `decrypt_failed` | "Định dạng dữ liệu của Zalo đã thay đổi, chưa giải mã được. Đã báo quản trị viên." |

- Chống bấm liên tục: nút "Đồng bộ lịch sử từ điện thoại" mờ khi có lượt đang chạy.

#### 4.6.14 Test cho bộ giải mã (không cần tài khoản thật)

Tự dựng tệp mẫu để test hai chiều:

1. Tạo 2 SQLite nhỏ có bảng `ChatContent` (đủ các cột ở 4.6.10, BinNet dựng bằng hàm ghi TLV ngược).
2. Nén nối tiếp bằng `xz` → dựng header ZDB4 đúng bố cục 4.6.7 (tính `xxh32`).
3. Mã hoá bằng AES-256-CBC IV 0 **từng khối 64 KiB**, đuôi lẻ chép nguyên, với khoá dẫn xuất từ một
   `aesKey` 32 byte; bọc `aesKey` bằng public key RSA của test.
4. Chạy pipeline PHP → so số tin, `msg_id` (cả hai nhánh GlbMsgId/`sync:`), direction, attachments,
   `sent_at` (giây và mili giây).
5. Ca biên: tệp > 64 KiB (bắt lỗi quên reset IV), tệp có độ dài không chia hết 16, entry `size=0`,
   XZ thừa/thiếu byte, BinNet lệch độ dài, `RefCliMsgId=0`.

Bộ sinh tệp `.db.crypt` giả (bước 2–3 ở trên; đã dùng để kiểm chứng 4.6.8a). Đưa vào
`tests/Support/` và gọi từ test thay vì `exec` CLI khi viết thành PHPUnit:

```php
<?php
// Tạo .db.crypt giả theo đúng định dạng: entries -> XZ -> container ZDB4 -> AES-CBC IV0 reset mỗi 64KiB.
[$_, $outDir, $sizesCsv, $trailing] = $argv + [null, null, null, '0'];
$sizes = array_map('intval', explode(',', $sizesCsv));
@mkdir($outDir, 0700, true);
$raw = '';
foreach ($sizes as $i => $s) { $raw .= $s ? substr("SQLite format 3\0" . random_bytes($s), 0, $s) : ''; }
file_put_contents("$outDir/raw.bin", $raw);
exec("xz -c -T1 $outDir/raw.bin > $outDir/raw.xz", $o, $rc); if ($rc) exit(1);
$xz = file_get_contents("$outDir/raw.xz");
$entries = ''; foreach ($sizes as $i => $s) { $n = "msg_{$i}.db"; $entries .= pack('N', strlen($n)) . $n . pack('N', $s); }
$body = pack('N', count($sizes)) . $entries . $xz;          // bắt đầu từ offset 14
$hashEnd = 14 + strlen($body);
$xxh = hexdec(hash('xxh32', $body));
$container = 'ZDB4.0' . pack('N', $hashEnd) . pack('N', $xxh) . $body . ($trailing === '1' ? random_bytes(37) : '');
$aesKey = random_bytes(32);
$key = substr(strtoupper(bin2hex($aesKey)), 0, 32);
$enc = '';
foreach (str_split($container, 65536) as $chunk) {
    $l = strlen($chunk) - strlen($chunk) % 16;
    $enc .= ($l ? openssl_encrypt(substr($chunk, 0, $l), 'aes-256-cbc', $key, OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING, str_repeat("\0", 16)) : '') . substr($chunk, $l);
}
file_put_contents("$outDir/in.db.crypt", $enc);
file_put_contents("$outDir/aes.key", $aesKey);
$md5 = []; $off = 0; foreach ($sizes as $s) { $md5[] = md5(substr($raw, $off, $s)); $off += $s; }
file_put_contents("$outDir/expected.json", json_encode($md5));
echo "fixture: container=" . strlen($container) . " bytes, enc=" . strlen($enc) . ", entries=" . count($sizes) . "\n";
```

Chạy: `php make_fixture.php <thư-mục> "40000,0,1500000,70001,3000000,17" 1` → sinh `in.db.crypt`,
`aes.key` (32 byte nhị phân), `expected.json` (md5 từng entry). Đối số cuối `1` = thêm rác sau `hashEnd`.

### 4.7 Kiểm chứng tầng giao thức (Phase 0)

Mục tiêu Phase 0 không còn là "viết được giao thức" mà là **kiểm chứng zca-php đủ dùng** trên tài
khoản phụ, qua đúng lớp bọc `app/Zalo/Protocol` (không gọi `Zca\…` thẳng từ lệnh probe):

1. `php artisan zalo:probe-login {accountId}`: chạy `ZaloLoginQr` (ảnh QR ghi ra tệp tạm, xoá sau),
   lưu credential, in `uid` và các khoá của service map. Chạy thêm `ZaloLoginCookie` với **credential
   xuất từ worker zca-js cũ** — phải đăng nhập được (để chuyển hệ thống không cần quét lại).
2. `php artisan zalo:probe-listen {accountId} --seconds=120`: mở listener, in loại sự kiện + `msg_id`
   (không in nội dung), đo RAM; thử mở 2–3 tài khoản cùng tiến trình trên một `Loop::run()`.
3. `php artisan zalo:probe-send {accountId} {threadId} "xin chào"`: chỉ chạy khi có xác nhận của
   người phụ trách — **tin gửi là thật**. Thử thêm: ảnh từ tiến trình không có listener; tệp PDF từ
   tiến trình có listener (đo thời gian chặn event loop của upload, ghi vào tài liệu vận hành).
4. Đối chiếu: cùng một tin, so `NormalizedMessage` từ PHP với bản worker Node cũ ghi ra (chạy song
   song trên tài khoản phụ — lưu ý mã 3000: hai listener cùng tài khoản sẽ đá nhau, nên đối chiếu
   bằng cách luân phiên hoặc bằng frame đã ghi lại) — mọi trường ở 4.5 phải khớp.
5. Ghi lại các chỗ zca-php khác `zca-js@2.1.2`+bản vá của hệ thống cũ (ngoài 3 thứ đã biết ở đầu mục 4)
   vào `docs/zca-php-khac-biet.md`.

---

## 5. LUỒNG NGHIỆP VỤ CHI TIẾT

### 5.1 Trạng thái tài khoản (state machine)

```
CREATED ──open──► STARTING ──có credential, login OK──────────────► READY
                     │                                               │  ▲
                     └─chưa có / hết hạn──► LOGIN_REQUIRED ──quét QR─┘  │ reconnect OK
                                                                        │
READY ──mất mạng / ws đóng bất thường──► DISCONNECTED ──backoff 1s→30s──┘
READY ──ws đóng mã 3000 (đăng nhập nơi khác) / 3003 (bị đá)──► RELOGIN_REQUIRED
STARTING ──login bằng cookie bị Zalo từ chối──► RELOGIN_REQUIRED
* ──close-session──► DISCONNECTED (giữ credential)
* ──is_enabled=false──► DISABLED
* ──lỗi không xác định (giải mã hỏng, cấu hình sai)──► ERROR (+ last_error)
```

Enum PHP: `CREATED, STARTING, LOGIN_REQUIRED, READY, BUSY, RELOGIN_REQUIRED, DISCONNECTED, ERROR, DISABLED`.
Nhãn tiếng Việt cho UI: READY → "Sẵn sàng" (xanh), LOGIN_REQUIRED/RELOGIN_REQUIRED → "Chờ đăng nhập"
(vàng), STARTING → "Đang kết nối" (xám + spinner), DISCONNECTED → "Mất kết nối" (cam),
ERROR → "Lỗi" (đỏ), DISABLED → "Đã tắt" (xám).

Mỗi lần trạng thái đổi: gateway RPUSH `{type:"status", account_id, status, own_id?, display_name?, avatar?, error?}`
→ consumer cập nhật `zalo_accounts`, `INCR zalo:ver:{id}`.

### 5.2 Tạo tài khoản

1. Admin/nhân viên nhập tên → `POST /api/zalo-accounts {name}`.
2. Kiểm tra hạn mức (nếu hệ thống có gói dịch vụ). Tạo bản ghi `status=CREATED`, `user_id=auth()->id()`,
   `gateway_shard = id % shards`, đồng thời gắn vào `zalo_account_user`.
3. Không gọi Zalo ở bước này.

### 5.3 Mở phiên + đăng nhập QR

```
UI                    Laravel web               Queue (zalo-login)          Zalo            Gateway
│ POST open-session ─►│                          │                           │                │
│                     │ có credential?            │                           │                │
│                     │ ├─ có: RPUSH cmd start ───┼───────────────────────────┼──────────────► │ login cookie → ws
│                     │ │   status=STARTING       │                           │                │
│                     │ └─ không: dispatch ──────►│ ZaloQrLoginJob            │                │
│                     │     status=LOGIN_REQUIRED │ ├─ lấy QR ───────────────►│                │
│ ◄─ 200 {status} ────│                           │ │  SET zalo:qr:{id}       │                │
│ poll GET qr (2s) ──►│ đọc zalo:qr:{id} ────────►│ ├─ chờ quét (long-poll) ─►│ người dùng quét│
│ hiện ảnh QR         │                           │ ├─ chờ xác nhận ─────────►│ bấm "Đăng nhập"│
│                     │                           │ ├─ nhận cookie, lưu credential (mã hoá)     │
│                     │                           │ └─ RPUSH cmd start ───────┼──────────────► │ login cookie → ws → READY
│ poll status ───────►│ READY                     │                           │                │
```

Quy tắc:

- `open-session` **trả về ngay**, không chờ quét. Giao diện poll `GET /api/zalo-accounts/{id}/qr`
  mỗi 2 giây (trả PNG hoặc JSON `{image: base64, state: "waiting_scan|scanned|expired|done", scanned_name, scanned_avatar}`)
  và `GET /status` mỗi 3 giây cho tới khi READY.
- QR hết hạn (~60–100 giây, chi tiết ở 4.2) → job tự sinh QR mới tối đa 3 lần, quá thì
  `state=expired`, UI hiện nút "Lấy mã mới".
- Khi người dùng đã quét (trạng thái `scanned`), hiện ảnh đại diện + tên Zalo vừa quét để họ biết
  đang đăng nhập đúng tài khoản.
- Chỉ **một** job QR cho một tài khoản tại một thời điểm: `Cache::lock("zalo:qr-login:{id}", 300)`.
- Đăng nhập xong: lưu `zalo_credentials`, KHÔNG log cookie. Sau đó luôn đi qua gateway `start`
  (gateway mới là nơi lấy `zpw_enk`, mở WebSocket và ghi `zalo:ctx`).
- Đăng nhập bằng mật khẩu: **không có** (giao thức chỉ hỗ trợ QR). Không bypass captcha/OTP.

### 5.4 Khởi động gateway và khôi phục phiên

1. `zalo:gateway --shard=N` khởi động: lấy các tài khoản `is_enabled=1`, `deleted_at IS NULL`,
   `gateway_shard=N`, có `zalo_credentials`, status ∉ {DISABLED}.
2. Đăng nhập lại bằng cookie **lần lượt từng tài khoản**: `Zca\Zalo::login()` là 2 request Guzzle
   đồng bộ, không chạy song song được trong một tiến trình. Giữa hai tài khoản nhả event loop
   (`Loop::addTimer(restore_gap_ms/1000, …)`) để các WebSocket đã mở kịp ping và nhận tin. Ước tính
   ~0,5–1s/tài khoản → 100 tài khoản mất 1–2 phút; nếu đo ở Phase 0 thấy quá chậm thì tăng số shard
   (mỗi shard khởi động độc lập, song song với nhau).
3. Mỗi tài khoản: `ZaloLoginCookie::login()` → đăng ký custom API (4.6.2) → ghi `zalo:ctx:{id}`
   (mã hoá) → gắn handler `ZaloListener` → `$api->listener->start(["retryOnClose" => false])` →
   chờ `cipher_key` → READY → RPUSH status. Sau khi đã `start()` hết, gateway chạy một `Loop::run()`.
4. Ngay khi WebSocket **connected lần đầu của phiên**: gửi yêu cầu "tin tồn" (old messages, 5.15)
   **một lần**. Cờ `hasRequestedOldMessages` chặn việc xin lại mỗi lần rớt mạng nối lại.
5. Tài khoản bị Zalo từ chối cookie → RELOGIN_REQUIRED, `last_error="Phiên Zalo đã hết hạn, hãy quét QR lại."`.

### 5.5 Nhận tin realtime (gateway)

1. Frame WebSocket tới → giải mã (4.4) → phân loại theo `cmd`.
2. Tin người dùng/nhóm → `MessageNormalizer` → `NormalizedMessage` (4.6) → RPUSH
   `{"type":"message","account_id":…, …}` vào `zalo:ingest`.
3. Sự kiện reaction, undo (thu hồi), group_event, friend_event → RPUSH `{"type":"event", "event":"reaction|undo|group|friend", …}`.
4. Cập nhật `zalo:session:{id}.last_event_at`.
5. Tin do **chính tài khoản** gửi (từ tool hoặc điện thoại) cũng về qua WebSocket → `direction=out`.
   Unique index sẽ nuốt bản trùng nếu đã có.
6. Sticker: tin chỉ mang **id**. Gateway tra chi tiết sticker (cache Redis vĩnh viễn, `zalo:sticker:{id}`)
   để điền `url`; tra lỗi thì dùng khuôn dự phòng
   `https://zalo-api.zadn.vn/api/emoticon/sticker/webpc?eid={id}&size=130`;
   không moi được id thì `content="[Sticker]"`. Id sticker có thể nằm ở các khoá `id`/`stickerId`/
   `sticker_id`/`uri` hoặc trong chuỗi `[^cateId.stickerId^]` — thử lần lượt. Việc tra cứu là HTTP
   đồng bộ (`getStickersDetail` của zca-php) → **không** làm trong gateway (2.4): gateway chỉ ghi id,
   consumer/job bổ sung `url` sau (đọc cache trước, cache trượt thì gọi `ZaloApi` bằng `zalo:ctx`).

### 5.6 Hàng đợi bền và không mất tin

Đây là mắt xích dễ mất dữ liệu nhất (dữ liệu không tái tạo được).

- Gateway RPUSH ngay khi nhận, không gom trong RAM lâu. Redis lỗi → giữ tạm trong mảng RAM tối đa
  `10_000` bản ghi, thử lại backoff 1s→30s; tràn thì bỏ bản **cũ nhất** và `Log::error`.
- Nhận SIGTERM → ngừng nhận lệnh mới, xả mảng RAM vào Redis, đóng WebSocket mã 1000, thoát.
- Consumer:
  ```
  khởi động: LMOVE toàn bộ zalo:ingest:processing → đầu zalo:ingest   (khôi phục lô dở)
  vòng lặp:
    gom tối đa batch_size bản ghi bằng LMOVE zalo:ingest → zalo:ingest:processing (BLMOVE chờ flush_ms)
    tách theo type: message / event / status
    ZaloMessageIngestService::ingest(messages)   ← chống trùng bằng unique index
    ZaloEventIngestService::ingest(events)
    ZaloAccountStatusService::apply(statuses)
    DEL zalo:ingest:processing (hoặc LREM từng phần tử)
  ```
- **Một hội thoại lỗi không được làm hỏng cả lô:** bọc từng hội thoại trong try/catch, ghi log,
  bỏ qua phần lỗi. Không ném lỗi ra ngoài để lô bị xử lý lại (gây xử lý trùng phần đã ghi).
- Lọc bỏ bản ghi của `account_id` không còn tồn tại (đã xoá) trước khi ghi — credential mồ côi
  từng làm hỏng nguyên lô của tài khoản khác.
- Trang health hiển thị `LLEN zalo:ingest` (tin đang chờ). Lớn hơn 1000 trong 1 phút → cảnh báo.

### 5.7 Ghi tin vào DB (ZaloMessageIngestService)

```
ingest(records):
  bỏ bản ghi thiếu account_id / thread_id / msg_id   (không có msg_id thì không chống trùng được)
  gom theo (account_id, thread_id)
  lọc account không tồn tại
  với mỗi nhóm (try/catch riêng):
     conversation = resolveConversation()          // firstOrCreate — hai lô song song
     senderNames  = realtimeSenderNames()          // nhóm: tra zalo_contacts cho sender thiếu tên
     rows = map(record → cột zalo_messages)
     upsert(rows, unique=[zalo_account_id,msg_id], update=['updated_at'])
         // tin đã có thì GIỮ NGUYÊN bản cũ; ngoại lệ: nếu bản cũ quote_payload NULL mà bản mới có → cập nhật
     markBackfillAsRead(conversation, batch)       // PHẢI chạy trước bước đếm
     refreshConversationSummary(conversation, batch)
     autoReplyTrigger(...)                         // nếu có module AI
     INCR zalo:ver:{account_id}
  sau khi commit hết: dispatch các job auto-reply / prune
```

**resolveConversation:**
- Tìm theo `(account_id, thread_id)` (kể cả bản ghi xoá mềm → khôi phục nếu có tin mới đến).
- Tạo mới: chat 1-1 đặt `display_name` tạm từ `sender_name` của tin **đến** đầu tiên; **nhóm để
  trống** (tin nhóm chỉ mang tên người gửi — từng có nhóm "[Vietec] Tập huấn" hiện thành "Billbee").
- `is_hidden` lấy từ cache `zalo:hidden:{id}` (CHỈ đọc cache, không gọi Zalo trong luồng ingest).

**refreshConversationSummary:**
- `unread_count = countUnread()` — **TÍNH LẠI** từ bảng tin, không cộng dồn (cộng dồn làm thổi
  phồng số chưa đọc mỗi lần lô bị gửi lại).
- Lấy tin mới nhất của lô; nếu `last_message_at` hiện tại **mới hơn** → chỉ lưu unread, không đẩy
  lùi preview (lô tới muộn).
- Cập nhật `last_message_preview` (cắt 120 ký tự; không có chữ thì `[Hình ảnh]`, `[Video]`,
  `[Tin nhắn thoại]`, `[Sticker]`, `[Liên kết]`, `[Tệp đính kèm]`, danh thiếp → `Danh thiếp`),
  `last_message_at`, `last_message_direction`.

**countUnread (thuật toán chuẩn):**
```
readUntil = conversation.last_read_at
lastOut   = MAX(sent_at) các tin direction='out' KHÔNG nằm trong zalo_agent_sent_messages
if lastOut > readUntil: readUntil = lastOut       // người thật trả lời (kể cả bằng điện thoại) = đã xem
unread = COUNT tin direction='in' AND (readUntil IS NULL OR sent_at > readUntil)
```
Tin do AI/tự động gửi bị loại vì agent trả lời ngay khi tin tới → mọi hội thoại bật AI về 0 chưa
đọc trước khi người trực kịp thấy.

**markBackfillAsRead:** nếu `last_read_at IS NULL` (chưa ai mở) **và** toàn bộ lô là `is_backfill`
→ `last_read_at = MAX(sent_at)` của lô. Hội thoại đã mở thì không đụng (bấm đồng bộ thủ công không
được xoá số chưa đọc đang chờ). Lô có lẫn tin mới → không đụng.

**Tin backfill KHÔNG BAO GIỜ kích hoạt auto-reply.**

### 5.8 Đọc danh sách hội thoại

`GET /api/zalo-accounts/{id}/conversations?limit=50&before_last_message_at=&before_id=`

- Lọc `is_hidden=0`, `deleted_at IS NULL`, sắp `last_message_at DESC, id DESC`, phân trang **con trỏ**
  (không OFFSET).
- **enrichConversations** cho các hàng trả về: tra `zalo_contacts`; tên danh bạ **luôn thắng**
  `display_name` (Zalo có 2 tên: `zaloName` người đó tự đặt, `displayName` là tên gợi nhớ tài khoản
  này đặt — app Zalo hiện `displayName`, ta phải hiện y hệt). Nhóm: tên + ảnh từ `getGroupInfo`.
  Id chưa có hoặc đã cũ (ảnh: 7 ngày; rỗng: 12 giờ) → dispatch `ResolveProfilesJob` (không chặn request).
- Tên hiển thị cuối: `custom_name → contact.display_name → display_name → thread_id`.
- Response mỗi hàng:
  ```json
  {"account_id":2,"thread_id":"8714…","thread_type":"user","name":"Em Bé","original_name":"Liễu Dương",
   "custom_name":null,"avatar_url":"…","last_message_preview":"Dạ em cảm ơn","last_message_at":"2026-…+07:00",
   "last_message_direction":"in","unread_count":2,"tags":[{"id":1,"name":"VIP","color":"#d92870"}],
   "is_friend":true}
  ```

Tìm kiếm `GET /search?keyword=` — tìm trên DB theo `custom_name`, `display_name`, tên trong
`zalo_contacts`, `thread_id` (escape `%`/`_`), loại hội thoại ẩn. Không hỏi Zalo.

### 5.9 Đọc tin nhắn

`GET /api/zalo-accounts/{id}/messages?conversation_key={thread_id}&limit=50&before_sent_at=&before_id=&mark_read=1`

```sql
SELECT * FROM zalo_messages WHERE zalo_conversation_id=?
  AND (sent_at < ? OR (sent_at = ? AND id < ?))     -- chỉ khi có con trỏ
ORDER BY sent_at DESC, id DESC LIMIT 51;             -- lấy 51 để biết has_more
```

- Trả về theo thứ tự **cũ → mới** (đảo lại sau khi query).
- Hội thoại ẩn → `{success:true, hidden:true, data:[]}` để UI đóng khung chat lặng lẽ.
- `mark_read=1` (chỉ controller giao diện bật; service mặc định **tắt** — AI/API đọc hộ máy không
  được xoá chưa đọc): `last_read_at = MAX(sent_at)` của hội thoại (**không phải `now()`** — đồng hồ
  Zalo có thể đi trước server), `unread_count=0`.
- Bổ sung cho từng tin: ảnh đại diện/tên người gửi (từ `zalo_contacts`; nhóm thiếu tên → tra
  thành viên nhóm), khối trích dẫn (ưu tiên bản ghi thật trong kho theo `quote_msg_id`, rơi về
  `quote_preview`), reactions (gom theo icon + đếm + danh sách tên), nhân viên đã gửi.
- Hình dạng một tin:
  ```json
  {"msg_id":"…","content":"…","direction":"in","attachments":[],"mentions":[],
   "senderId":"…","senderName":"…","senderAvatarUrl":"…","sentByUserName":"Lan",
   "sentAt":"…","quote":{"msgId":"…","senderName":"…","text":"…","attachment":null},
   "canQuote":true,"canForward":true,"isRecalled":false,
   "reactions":[{"icon":"👍","count":3,"actors":["An","Bình","Chi"],"mine":false}]}
  ```
- `pagination: {limit, has_more, next_before_sent_at, next_before_id}`.
- Ảnh gửi kèm chữ là MỘT tin; chữ nằm ở `title` của ảnh → khi chuẩn hoá đưa vào `content`.

### 5.10 Gửi tin

`POST /api/zalo-accounts/{id}/messages` (multipart): `conversation_key`, `content`, `attachments[]`,
`reply_to_msg_id?`, `mentions?` (JSON), `client_id` (id tạm của bong bóng optimistic).

```
SendMessageRequest: content ≤ 2000 ký tự hoặc có tệp; tệp theo config zalo.attachments
EnsureZaloAccountAccess: user có quyền với tài khoản {id}                       [GỬI NHẦM]
ZaloSendService::send():
  account phải READY, có zalo:ctx → nếu thiếu ctx: RPUSH cmd start, trả SESSION_NOT_READY
  conversation = tìm (account, thread_id); thread_type = conversation.thread_type ?? 'user'
  nếu reply_to_msg_id: quote = zalo_messages.quote_payload; NULL → 422
        "Không trả lời được tin này: hệ thống không còn dữ liệu trích dẫn của nó. Hãy gửi như tin thường."
        (KHÔNG được lặng lẽ gửi thành tin thường)
  Cache::lock("zalo:send:{account}:{thread}", 30)   // giữ thứ tự tin trong cùng hội thoại
  chỉ ảnh (+ chữ): ngay tại web — sendMessage(["msg" => caption, "attachments" => ảnh từ bộ nhớ]) qua zalo:ctx
  có video/tệp: KHÔNG gọi ở web — ghi tệp vào storage dùng chung, RPUSH zalo:gw:cmd:{shard}
        {cmd:"send_files", request_id, account_id, thread_id, thread_type, files:[path,name,mime], caption}
        rồi BLPOP zalo:gw:reply:{request_id} (timeout = upload_timeout + 30s); hết giờ → SEND_UNCERTAIN
  chỉ chữ: sendMessage (có quote → kèm "quote"; có mention → kèm "mentions")
  thành công → nhận msgId
     ghi zalo_user_sent_messages (user hiện tại) / zalo_agent_sent_messages (nếu AI gửi)
     cập nhật preview hội thoại ngay (để sidebar nhảy lên, không đợi tin vọng về)
     KHÔNG tự insert zalo_messages — tin vọng về qua WebSocket sẽ ghi (đủ quote_payload)
  trả {success:true, data:{msg_id, client_id}}
```

- **[GỬI NHẦM]** Hội thoại PHẢI có bản ghi `zalo_conversations` để biết `thread_type`. Mở hội thoại
  mới từ danh bạ PHẢI đi qua `POST contacts/open` (tạo bản ghi với đúng `thread_type`) — mặc định
  `user` cho một nhóm sẽ bị Zalo từ chối.
- Ảnh: Zalo bắt buộc `width`/`height` → đọc bằng `getimagesizefromstring()` (PNG/JPEG/GIF/WebP/BMP).
- Ảnh gửi thẳng từ bộ nhớ (UploadedFile → nội dung, nguồn `["data" => $bytes, "filename", "metadata"]`
  của zca-php), không ghi tệp tạm.
- **Vì sao video/tệp phải qua gateway:** `UploadAttachment` của zca-php upload xong vẫn chờ sự kiện
  `file_done` trên WebSocket của **chính `Zca\API` đó** (gói ném lỗi ngay nếu listener chưa `start()`).
  Tiến trình web không được mở listener riêng — mở là đá phiên của gateway (mã 3000). Gateway chạy
  `send_files` trong `React\Async\async()` để phần chờ `file_done` nhả loop; còn phần POST các khúc tệp
  vẫn chặn loop trong lúc upload (đo ở Phase 0; quá lâu thì giảm `max_video_mb`/`max_file_mb` hoặc
  tách tài khoản nhiều tệp ra shard riêng). Tệp tạm ở storage dùng chung xoá ngay sau khi gửi (thành
  công hay lỗi), dọn sót bằng scheduler (> 1 giờ).
- Timeout xếp tầng: HTTP tới Zalo 120s cho tệp → `max_execution_time 180` → nginx
  `fastcgi_read_timeout 180s`. Laravel bỏ cuộc giữa chừng thì tin **vẫn có thể đã gửi** → UI báo
  "Không chắc đã gửi, hãy kiểm tra trước khi gửi lại" thay vì "lỗi".
- Không retry tự động lời gọi gửi tin (nguy cơ gửi trùng). Chỉ retry khi lỗi chắc chắn xảy ra
  **trước** khi request rời máy (thiếu ctx, lỗi DNS/kết nối).

### 5.11 Reaction, thu hồi, xoá, chuyển tiếp

| Thao tác | Route | Quy tắc |
|---|---|---|
| Thả cảm xúc | `POST messages/{msgId}/reaction {icon}` | 6 icon: 👍 ❤️ 😆 😮 😢 😡 (+ bỏ cảm xúc). Cần tin gốc (msgId, cliMsgId, thread). Ghi ngay vào `zalo_message_reactions` với actor = chính mình để UI cập nhật; sự kiện vọng về sẽ upsert trùng |
| Nhận reaction | sự kiện `reaction` | Chuẩn hoá mã icon Zalo về 6 icon kinh điển nếu khớp, giữ `raw_icon`; upsert theo `(account, msg_id, actor_id)`; icon rỗng = bỏ reaction → xoá dòng |
| Thu hồi (cho mọi người) | `POST messages/{msgId}/undo` | Chỉ tin `out`. Zalo giới hạn thời gian thu hồi; lỗi → báo rõ |
| Nhận thu hồi | sự kiện `undo` | `is_recalled=1`, `recalled_at`; UI hiện "Tin nhắn đã bị thu hồi" thay nội dung/đính kèm |
| Xoá phía tôi | `DELETE messages/{msgId}` | Gọi Zalo xoá phía mình; xoá/ẩn bản ghi ở DB (NÊN xoá mềm) |
| Chuyển tiếp | `POST messages/{msgId}/forward {target_thread_ids[]}` | Chữ: dùng API forward. Ảnh/tệp: tải lại từ URL CDN rồi gửi như tin mới (API forward không nhận ảnh). Loại lạ (vị trí, bình chọn, thẻ ngân hàng) → `canForward=false`. Chỉ cho chọn đích **trong cùng tài khoản** |

### 5.12 Danh bạ

`GET /api/zalo-accounts/{id}/contacts?refresh=0`

- Gọi `getAllFriends` + `getAllGroups` (+ `getGroupInfo` theo lô cho tên/ảnh nhóm), cache 10 phút
  (`zalo:contacts:{id}`), đồng thời upsert vào `zalo_contacts` (để phần tra ảnh dùng chung).
- Loại bỏ người/nhóm đang ẩn (5.13) — không lọc thì bấm một cái là hội thoại ẩn mở toang.
- Lọc từ khoá **tại trình duyệt**, bỏ dấu hai phía ("hung" khớp "Hưng").
- Danh bạ **không gộp nhiều tài khoản** (cùng một người hiện nhiều dòng không biết mở bằng tài khoản nào) → màn danh bạ có dãy chip chọn một tài khoản.
- Bấm liên hệ → `POST contacts/open {thread_id, thread_type, name}` → tạo/khôi phục
  `zalo_conversations` → UI chuyển sang màn chat và mở hội thoại (đánh dấu `_openedAt` để nằm đầu
  danh sách dù chưa có tin).

Tra hồ sơ theo lô (`ResolveProfilesJob`): `getUserInfo(uids[])` + `getGroupInfo(gids[])`, tra được cả
người **ngoài danh bạ** (người lạ nhắn tới, thành viên nhóm). Mọi lỗi nuốt — thiếu ảnh thì UI vẽ
chữ cái đầu, không được làm hỏng việc đọc tin.

### 5.13 Hội thoại ẩn

Zalo cho ẩn hội thoại sau mã PIN; tin của hội thoại ẩn về qua WebSocket **y hệt tin thường**.
Cách duy nhất biết: gọi `getHiddenConversations`.

- `ZaloHiddenConversationService::sync(accountId)`: gọi Zalo, cache 60 giây, áp vào cột
  `is_hidden` (set 1 cho danh sách, 0 cho phần còn lại). Scheduler gọi mỗi phút cho tài khoản READY;
  cũng gọi khi tài khoản vừa READY (nạp cache trước khi tin đầu tiên tới).
- **Hỏi lỗi → giữ nguyên cờ cũ.** Coi lỗi là "không có gì bị ẩn" sẽ làm mọi hội thoại riêng tư bật
  ra đúng lúc hệ thống trục trặc.
- Mã PIN Zalo trả kèm → bỏ ngay, không log, không lưu.
- Bịt mọi cửa: danh sách, tìm kiếm, đọc tin (`hidden:true`), danh bạ, auto-reply (không chạy trong
  hội thoại ẩn). Ẩn ≠ xoá: tin vẫn được ghi đầy đủ.

### 5.14 Đổi tên hiển thị, xoá hội thoại, gắn thẻ

- Bấm đúp tên ở đầu khung chat → ô sửa inline → `PATCH /conversations {thread_id, name}` → ghi
  `custom_name` (rỗng = xoá, rơi lại tên Zalo). Hiện dòng nhỏ "Tên Zalo: …" để người dùng biết tên gốc.
- Xoá hội thoại khỏi hệ thống: `DELETE /conversations {thread_id}` sau hộp thoại xác nhận
  ("Tin nhắn đã lưu ở đây không lấy lại được từ Zalo"). NÊN xoá mềm. Chỉ admin.
- Gắn/bỏ thẻ: `POST /conversations/tags {thread_id, tag_id}` (toggle).

### 5.15 Đồng bộ tin tồn (old messages)

- Gửi qua chính WebSocket: `$api->listener->requestOldMessages(ThreadType::User)` và
  `(ThreadType::Group)`; kết quả về sự kiện `old_messages` (4.4). Zalo trả về **hàng đợi tin
  chưa giao cho client này**, KHÔNG phải lịch sử tuỳ ý: tài khoản vừa nối liên tục thì trả 0; mới
  khôi phục phiên thì nhận vài chục tin tồn. Nó **vá lỗ hổng mất tin khi gateway chết**.
- Tự động 1 lần/phiên khi ws connected; thủ công qua nút "Đồng bộ tin nhắn"
  (`POST /api/zalo-accounts/{id}/sync` → RPUSH cmd `request_old_messages`). Nút trên giao diện áp
  dụng cho **tất cả** tài khoản đang tích chọn.
- 200 nghĩa là **đã gửi yêu cầu**, không phải đã có dữ liệu → UI tải lại danh sách ở mốc 2s/6s/12s.
- Tin trả về mang `is_backfill=true`: không kích hoạt auto-reply, không thắp chưa đọc (5.7).
- Các đường đã thử và **chết** (đừng thử lại): API lịch sử chat 1-1 qua HTTP (404), `getGroupChatHistory`
  (`/api/group/history` 404 — zca-php vẫn có phương thức này vì port nguyên zca-js, nhưng đừng dùng), tuỳ chọn "đồng bộ tin nhắn" ở chế độ QR web (không có dữ liệu tới).

### 5.16 Xoá tài khoản và đổi chủ lịch sử

- Xoá = **xoá mềm** `zalo_accounts` + xoá `zalo_credentials` + RPUSH cmd `forget` (gateway đóng
  WebSocket, xoá `zalo:ctx`). Nếu chỉ đóng phiên mà để credential, lần gateway khởi động sau sẽ khôi
  phục phiên cho tài khoản không còn tồn tại; nếu người dùng tạo lại tài khoản thì **hai phiên cùng
  một tài khoản Zalo đá nhau bằng mã đóng 3000**.
- Khi một tài khoản báo READY kèm `own_id`: ghi `zalo_uid` **trước**, rồi chạy
  `adoptHistoryFromDeletedAccount()` **ở mọi lần báo trạng thái** (không gắn với "uid có đổi không";
  lỗi được bắt lại, không làm hỏng callback):
  ```
  oldIds = zalo_accounts đã xoá mềm có cùng zalo_uid, id ≠ account.id
  transaction:
    với mỗi bảng dữ liệu (conversations, messages, contacts, reactions, friend_requests,
                           agent_sent, user_sent, …):
       xoá các dòng của oldIds đụng unique với dòng của account mới   (giữ bản MỚI)
       UPDATE bảng SET zalo_account_id = account.id WHERE zalo_account_id IN oldIds
    forceDelete oldIds
  ```
  Đổi chủ, không sao chép — `zalo_messages.zalo_conversation_id` giữ nguyên nên mọi liên kết còn.
  Câu xoá dòng đụng nhau PHẢI viết được trên MySQL (không subquery vào chính bảng đang DELETE —
  lỗi 1093; tách thành SELECT id trước rồi DELETE theo id).
- Xoá nhân viên: `zalo_accounts.user_id = NULL` (không xoá tài khoản Zalo — mất lịch sử); tài khoản
  "không có chủ" chỉ admin thấy để bàn giao.

### 5.17 Đồng bộ toàn bộ lịch sử từ điện thoại (`pull_mobile_msg`) — tuỳ chọn, phase 4

Chỉ làm sau khi mọi thứ khác ổn. Tóm tắt luồng (đặc tả đầy đủ thuật toán giải mã, định dạng tệp,
mã PHP và test ở **mục 4.6**):

```
1. Tài khoản READY. Người dùng bấm "Đồng bộ lịch sử từ điện thoại".
2. Job MobileSyncJob: sinh cặp RSA-2048 tạm (openssl_pkey_new), public key SPKI base64 (bỏ header/footer).
3. Gọi pull_mobile_msg {pc_name:"Web", public_key, from_seq_id: lastSeq, is_retry:0, min_seq_id:0, temp_key:"", imei}.
   Response RỖNG — dữ liệu về qua WebSocket (cmd 601, act_type "syncmsgmb").
4. UI hiện màn chờ: "Mở Zalo trên điện thoại và bấm Đồng ý" + đếm ngược 120s + nút Thử lại.
5. Gateway nhận sự kiện: user_confirm → status confirmed; syncmsg_info → {url, encrypted_key, file_size,
   checksum_code, from_seq_id, is_full_transfer, db_info}; transfer_error → {can_retry, error_code, error_msg}.
   Gateway RPUSH event → job tiếp tục (job đọc trạng thái từ bảng zalo_mobile_sync_runs).
6. Tải file (stream ra đĩa), kiểm tra size + MD5 (CDN có thể 404 lúc đầu → thử lại vài lần).
7. Giải khoá AES = RSA-PKCS1 decrypt(encrypted_key) → đúng 32 byte.
8. Giải mã .db.crypt → container ZDB4.0 → XZ → nhiều SQLite ChatContent (mỗi DB một thread).
9. Đọc từng DB, chuẩn hoá về NormalizedMessage (is_backfill=true), ghi theo lô qua ZaloMessageIngestService
   (đi đường chậm có backpressure, không RPUSH ồ ạt vào zalo:ingest).
10. Lưu from_seq_id/imported SAU khi ghi xong lô cuối. Xoá file tạm + private key.
```

Rủi ro: file chứa **toàn bộ** hội thoại kể cả của bên thứ ba → xoá ngay sau import, ghi rõ trong
điều khoản. Một lần thật: 618 thread / 337.267 tin.

### 5.18 Kết bạn

- Tra số điện thoại: `POST users/find {phone}` → hiện thẻ ảnh + tên để xác nhận đúng người → bấm thẻ
  mở hội thoại (qua `contacts/open`).
- Trong hội thoại 1-1 với người **chưa là bạn**: thanh "Kết bạn" phía trên ô soạn → gửi lời mời
  (`POST friends/requests {user_id, message}`). Trạng thái lấy từ Zalo (`getFriendRequestStatus`):
  đã gửi chờ đồng ý → hiện "Đã gửi lời mời kết bạn, đang chờ đồng ý" (kể cả lời mời gửi từ điện thoại).
  Ẩn thanh với tài khoản hệ thống Zalo/OA (không kết bạn được).
- Lời mời đến (sự kiện friend_event loại REQUEST) → `zalo_friend_requests`; danh sách ở màn danh bạ
  với nút Chấp nhận/Từ chối. ADD/REMOVE/REJECT/UNDO cập nhật trạng thái + xoá cache danh bạ.
- Trong nhóm: bấm tên/ảnh người gửi hoặc thẻ @ → thẻ nhỏ "Kết bạn" / "Nhắn tin riêng".
- Xoá bạn: nút trên dòng ở tab Bạn bè, có xác nhận.

### 5.19 Nhóm

- Tạo nhóm (`POST groups {name, member_ids[]}`), xem thành viên (`getGroupInfo` lấy id + `getGroupMembersInfo`
  lấy tên/ảnh — ghép hai lần gọi), thêm/xoá thành viên, đổi tên, đổi ảnh.
- Sự kiện group_event `update`/`update_avatar` vá thẳng tên/ảnh vào `zalo_contacts`; loại khác chỉ xoá cache danh bạ.
- Nút "⚙ Nhóm" chỉ hiện với hội thoại nhóm.

### 5.20 Tin mẫu và thẻ

- Tin mẫu: `code` không có `/`; trong ô soạn gõ `/` mở danh sách gợi ý lọc theo mã/nội dung,
  ↑/↓ chọn, Enter/Tab chèn (thay đoạn `/xxx` bằng nội dung), Esc đóng. Nút `/ [số lượng]` cạnh ô soạn.
- Thẻ: thanh thẻ ngay trên ô soạn; thẻ đã gắn nền đặc, chưa gắn chỉ viền; hiện thẻ dưới mỗi hàng
  hội thoại ở sidebar. Quản lý thẻ (tạo/sửa màu/xoá/chuyển thẻ) ở trang cài đặt (admin).

---

## 6. API NỘI BỘ CHO GIAO DIỆN

Tất cả nằm dưới `routes/api.php`, nhóm `auth` (session web — thêm middleware session vào nhóm api,
gửi kèm CSRF token qua header `X-CSRF-TOKEN` từ thẻ `<meta name="csrf-token">`). Mọi route có
`{id}` PHẢI gắn middleware `zalo.account` (**[GỬI NHẦM]** bỏ sót một route là nhân viên thao tác
được trên tài khoản của người khác).

Định dạng phản hồi thống nhất:
```json
{"success": true, "data": …, "pagination": …}
{"success": false, "message": "Câu tiếng Việt cho người dùng", "error": {"code": "SESSION_NOT_READY"}}
```

| Method | Path | Mô tả |
|---|---|---|
| GET | `/zalo-accounts` | Danh sách tài khoản user được thấy (kèm status, nhãn, `is_owner`) |
| POST | `/zalo-accounts` | Tạo `{name}` |
| PUT | `/zalo-accounts/{id}` | Sửa tên, `is_enabled` |
| DELETE | `/zalo-accounts/{id}` | Xoá mềm + quên credential |
| POST | `/zalo-accounts/{id}/open-session` | Mở phiên (5.3) |
| POST | `/zalo-accounts/{id}/close-session` | Đóng phiên, giữ credential |
| POST | `/zalo-accounts/{id}/relogin` | Xoá credential, bắt quét QR lại |
| GET | `/zalo-accounts/{id}/status` | Trạng thái (DB + `zalo:session`) |
| GET | `/zalo-accounts/{id}/qr` | Ảnh QR + trạng thái quét |
| PATCH | `/zalo-accounts/chat-active` | Lưu danh sách tài khoản tích chọn `{ids:[]}` |
| GET | `/chat/changes?accounts=1,2` | `{versions:{"1":123,"2":88}}` — rẻ, chỉ đọc Redis (7.6) |
| GET | `/zalo-accounts/{id}/conversations` | 5.8 |
| PATCH | `/zalo-accounts/{id}/conversations` | Đổi tên `{thread_id, name}` |
| DELETE | `/zalo-accounts/{id}/conversations` | Xoá `{thread_id}` |
| POST | `/zalo-accounts/{id}/conversations/tags` | Toggle thẻ |
| GET | `/zalo-accounts/{id}/search?keyword=` | Tìm hội thoại |
| GET | `/zalo-accounts/{id}/messages` | 5.9 |
| POST | `/zalo-accounts/{id}/messages` | 5.10 |
| POST | `/zalo-accounts/{id}/messages/{msgId}/reaction` | `{icon}` |
| POST | `/zalo-accounts/{id}/messages/{msgId}/undo` | Thu hồi |
| DELETE | `/zalo-accounts/{id}/messages/{msgId}` | Xoá phía tôi |
| POST | `/zalo-accounts/{id}/messages/{msgId}/forward` | `{target_thread_ids:[]}` |
| POST | `/zalo-accounts/{id}/sync` | Xin tin tồn |
| POST/GET | `/zalo-accounts/{id}/sync-mobile` | 5.17 |
| GET | `/zalo-accounts/{id}/contacts?refresh=` | Danh bạ |
| POST | `/zalo-accounts/{id}/contacts/open` | `{thread_id, thread_type, name}` |
| GET | `/zalo-accounts/{id}/stickers/search?keyword=` | Tìm sticker |
| GET | `/zalo-accounts/{id}/stickers/categories/{cateId}` | Một bộ sticker |
| POST | `/zalo-accounts/{id}/stickers` | `{conversation_key, sticker_id, cate_id, type}` |
| POST | `/zalo-accounts/{id}/cards` | Danh thiếp `{conversation_key, user_id, phone?}` |
| POST | `/zalo-accounts/{id}/videos` | `{conversation_key, video_url, thumbnail_url, msg?}` |
| POST | `/zalo-accounts/{id}/bank-cards` | `{conversation_key, bin_bank, num_acc_bank, name_acc_bank?}` |
| POST | `/zalo-accounts/{id}/users/find` | `{phone}` |
| GET | `/zalo-accounts/{id}/friends/requests` | Lời mời đến |
| POST | `/zalo-accounts/{id}/friends/requests` | Gửi lời mời |
| GET | `/zalo-accounts/{id}/friends/{userId}/status` | Trạng thái kết bạn |
| POST | `/zalo-accounts/{id}/friends/{userId}/accept` \| `reject` \| `undo-request` | |
| DELETE | `/zalo-accounts/{id}/friends/{userId}` | Xoá bạn |
| POST | `/zalo-accounts/{id}/groups` | Tạo nhóm |
| GET/POST/DELETE | `/zalo-accounts/{id}/groups/{groupId}/members` | Thành viên |
| PATCH | `/zalo-accounts/{id}/groups/{groupId}` | Đổi tên |
| POST | `/zalo-accounts/{id}/groups/{groupId}/avatar` | Đổi ảnh |
| GET | `/tags/all`, `/message-templates/all` | Dữ liệu cho màn chat |
| CRUD | `/tags`, `/message-templates`, `/users` | Admin |

---

## 7. GIAO DIỆN VÀ TRẢI NGHIỆM (UI/UX)

### 7.1 Nguyên tắc nghiệm thu UX (mọi màn PHẢI đạt)

1. **Không bao giờ màn hình trắng / nhảy layout.** Skeleton đúng kích thước thật (hàng hội thoại
   cao 64px, bong bóng tin xen kẽ trái/phải), container giữ chiều cao cố định khi tải.
2. **Chuyển hội thoại phản hồi < 100ms** từ cache phía trình duyệt; dữ liệu mới đến sau
   (stale-while-revalidate). Cache không xoá khi chuyển qua lại.
3. **Optimistic UI khi gửi:** bong bóng hiện ngay ở trạng thái "đang gửi" (mờ 60% + spinner nhỏ ở
   góc), thành công → bình thường, lỗi → viền đỏ + dòng "Gửi thất bại · Thử lại" (nút Thử lại
   **có hỏi xác nhận**).
4. **Enter gửi thẳng, Shift+Enter xuống dòng**, không hỏi xác nhận. Bù lại PHẢI có: banner mảnh
   "Tin gửi từ đây là tin thật trên Zalo của **{tên tài khoản}**" luôn ở đầu khung chat, và tin lỗi
   không bao giờ biến mất.
5. **Đổi hội thoại thì xoá hết tệp đang chờ gửi và thanh trích dẫn** — giữ lại là một cú Enter
   sau đó ảnh bay nhầm người **[GỬI NHẦM]**. Nội dung chữ đang soạn dở NÊN lưu nháp theo từng hội
   thoại (Map trong RAM) và khôi phục khi quay lại.
6. **Cuộn:** tải tin cũ thì giữ nguyên vị trí (đo `scrollHeight` trước/sau, bù chênh lệch). Tự
   cuộn xuống đáy CHỈ khi người dùng đang ở đáy (cách đáy < 80px); nếu không, hiện nút nổi
   "↓ Tin mới (n)".
7. **Mọi thao tác > 300ms có phản hồi thị giác** (spinner trên nút, nút bị disable).
8. **Mọi lỗi là câu tiếng Việt người thường hiểu** (bảng mã lỗi ở Phụ lục A), không phải mã thô.
9. Tôn trọng `prefers-reduced-motion`; mọi nút icon có `aria-label`/`title`; điều hướng bàn phím được.

### 7.2 Bố cục màn Trò chuyện (`/chat`)

```
┌──────┬──────────────────────────┬──────────────────────────────────────────────┐
│ RAIL │  CỘT GIỮA (340px)        │  KHUNG CHAT (phần còn lại)                    │
│ 64px │                          │                                              │
│      │ [Tài khoản đang bật ▾]   │ ┌ Header: ảnh · Tên (bấm đúp sửa) · nhãn TK  ┐│
│ [QD] │ [🔄 Đồng bộ tin nhắn]     │ │ [⚙ Nhóm] [🤖 AI] [↻] [🗑]                   ││
│      │ [🔍 Tìm bạn bè, nhóm…]    │ └───────────────────────────────────────────┘│
│ 💬   │ ⚠ Không tải được: Beta    │ ⚠ Banner: Tin gửi từ đây là tin thật…        │
│ 📒   │ ┌──────────────────────┐ │                                              │
│ ⚙    │ │●Ảnh Tên        10:24 │ │   (tin cũ hơn… tự tải khi cuộn lên đỉnh)      │
│      │ │  Preview…   [2] [QD] │ │   ┌─────────┐                                 │
│      │ │  [VIP][Khách HN]     │ │   │ Bong bóng│ ← đến: trái, nền trắng         │
│      │ └──────────────────────┘ │   └─────────┘                                 │
│      │  … (cuộn vô hạn)          │                 ┌──────────┐                   │
│      │  [Tải thêm hội thoại]     │                 │ Bong bóng │ → đi: phải, hồng │
│ ⏻    │                          │                 └──────────┘                   │
│      │                          │ ── Thanh thẻ: [VIP] [Tiềm năng] [+] ──        │
│      │                          │ ── Thanh kết bạn (nếu chưa là bạn) ──         │
│      │                          │ ── Thanh trích dẫn: ↩ Trả lời An: "…" [×] ──  │
│      │                          │ ── Khay tệp: [ảnh][ảnh][📄 bao-gia.pdf ×] ──  │
│      │                          │ [🖼][😊][/ 12][➕] [ Nhập tin nhắn…      ] [Gửi]│
└──────┴──────────────────────────┴──────────────────────────────────────────────┘
```

- **Rail** (nền tím đậm `--app-rail`): ô chữ viết tắt tài khoản (bấm mở popover tích chọn tài
  khoản), 💬 Trò chuyện, 📒 Danh bạ, ⚙ Cài đặt (chỉ admin), dưới cùng ⏻ Đăng xuất. Chấm đỏ trên 💬
  nếu tổng chưa đọc > 0.
- **Popover tài khoản:** danh sách checkbox, mỗi dòng: tên, nhãn trạng thái màu, số chưa đọc. Lựa
  chọn lưu vào `users.chat_active_zalo_account_ids` (PATCH, debounce 500ms) để đổi máy vẫn giữ.
- **Hàng hội thoại** (64px): avatar 44px (ảnh hoặc chữ cái đầu trên nền màu băm từ id), tên (đậm
  nếu chưa đọc), preview 1 dòng (tiền tố "Bạn: " nếu tin đi), giờ tương đối (vừa xong / 5 phút /
  10:24 / Hôm qua / 12/10), huy hiệu chưa đọc đỏ (99+), **chip tên tài khoản** khi đang bật > 1 tài
  khoản (**[GỬI NHẦM]** phải nhìn ra hội thoại thuộc tài khoản nào), dòng thẻ màu.
- **Danh sách trộn đa tài khoản:** gọi song song `/conversations` cho từng tài khoản rồi trộn, sắp
  `last_message_at DESC` (hội thoại vừa mở từ danh bạ dùng `_openedAt`). Một tài khoản lỗi chỉ hiện
  dải "Không tải được hội thoại của: Beta", tài khoản khác vẫn chạy. KHÔNG làm endpoint gộp phía server.
- **Định danh hội thoại phía client PHẢI kèm tài khoản:** `key = accountId + "::" + threadId`
  (**[GỬI NHẦM]** cùng một người có thể nằm trong hai tài khoản). `selectConversation()` chỉ nhận
  object `{accountId, threadId,…}`, không nhận chuỗi `threadId` trần. Mọi lời gọi đọc/gửi/đổi
  tên/thẻ đi theo `selectedConversation.accountId`, không theo "tài khoản hiện hành" chung.
- Tắt một tài khoản trong popover → hội thoại của nó biến mất khỏi danh sách; nếu đang mở hội thoại
  của nó → đóng khung chat.

### 7.3 Bong bóng tin nhắn

- Đến: trái, nền `--app-message-in` (trắng, viền mảnh); đi: phải, nền `--app-message-out` (hồng nhạt).
- Nhóm tin liên tiếp cùng người gửi trong 2 phút: chỉ tin đầu hiện tên + avatar (trong nhóm), các
  tin sau thụt cùng lề.
- Dải phân cách ngày: "Hôm nay", "Hôm qua", "Thứ Hai, 12/10/2026".
- Giờ `HH:mm` ở cuối dòng chữ cuối; tin đi có thêm "· Lan" (nhân viên đã gửi) khi khác người đang xem.
- Nội dung chữ: escape HTML, giữ xuống dòng, tự nhận diện link (`target="_blank" rel="noopener noreferrer"`),
  thẻ @ tô màu theo `mentions[{pos,len}]`.
- Đính kèm — **mỗi đính kèm dựng đúng MỘT phần tử theo loại**:
  - `image`: `<img loading="lazy" referrerpolicy="no-referrer">`, src = `dataUrl → url → thumb_url`;
    lỗi tải → thử `thumb_url` → rơi về liên kết "Mở ảnh" (URL CDN Zalo có hạn dùng). Album nhiều ảnh: lưới 2–3 cột.
    Bấm ảnh → lightbox (Esc đóng, ←/→ chuyển ảnh trong hội thoại).
  - `sticker`: ảnh 120px, không khung bong bóng.
  - `video`: `<video controls preload="metadata" poster=thumb_url>`.
  - `audio`: `<audio controls>`.
  - `file`: thẻ biểu tượng theo đuôi (PDF đỏ, Word xanh dương, Excel xanh lá, ZIP xám) + tên + dung lượng + nút tải.
  - `link`: thẻ tiêu đề + mô tả + ảnh nhỏ (ảnh chỉ trang trí).
  - `card` (danh thiếp): ảnh + tên + nút "Gọi"/"Mã QR".
- Khối trích dẫn trong bong bóng: viền trái màu nhấn, tên người + 1 dòng chữ/“[Hình ảnh]”; bấm →
  cuộn tới tin gốc (tìm theo `data-msg-id`, nhấp nháy nền 1 giây; chưa tải thì tải thêm tin cũ tới khi thấy, tối đa 5 trang).
- Tin bị thu hồi: chữ nghiêng xám "Tin nhắn đã bị thu hồi", ẩn đính kèm.
- Chip reaction dưới bong bóng: "👍 3 ❤️ 1", hover hiện tên người; chip của mình viền màu nhấn.
- Hover bong bóng hiện nút 😊 nhỏ để thả cảm xúc nhanh.
- **Menu chuột phải** (cũng mở bằng nút "⋯" trên mobile/nhấn giữ 500ms): Trả lời · Copy tin nhắn ·
  Chuyển tiếp · Thu hồi (chỉ tin đi) · Xoá phía tôi. "Trả lời" mờ khi `canQuote=false` kèm `title`
  "Tin này cũ hơn ngày hệ thống bắt đầu lưu dữ liệu trích dẫn"; "Chuyển tiếp" mờ khi `canForward=false`.
  Menu `position:fixed` theo toạ độ con trỏ, tự lật khi chạm mép màn hình, Esc/bấm ngoài để đóng.

### 7.4 Ô soạn tin

- `<textarea>` tự giãn 1→6 dòng; placeholder "Nhập tin nhắn, dán hoặc kéo thả ảnh/video/tài liệu vào đây".
- **Dán (paste)**: lấy `clipboardData.files` → thêm vào khay. **Kéo-thả**: vùng thả phủ toàn khung
  chat, viền nét đứt màu nhấn "Thả tệp để gửi".
- Khay tệp: ảnh xem trước 64px (`URL.createObjectURL`, nhớ `revokeObjectURL` khi bỏ), tài liệu =
  icon + tên; nút × từng tệp. Kiểm tra trần ngay tại trình duyệt từ `window.ZALO_LIMITS` (nhúng từ
  `config/zalo.attachments` vào blade): quá → thông báo cụ thể "Ảnh tối đa 5MB: anh-1.jpg (7,2MB)".
- 🖼 mở `<input type="file" multiple accept="image/*,video/*,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.txt,.csv,.zip">`.
- 😊 bảng emoji 8 nhóm (Mặt cười, Cử chỉ, Trái tim, Động vật, Đồ ăn, Hoạt động, Đồ vật, Ký hiệu), chèn tại con trỏ.
- Sticker: bảng có ô tìm theo từ khoá, tab "Gần đây" (lưu `localStorage`, bọc try/catch) và từng bộ.
- `/` → gợi ý tin mẫu (5.20). `@` trong nhóm → bảng thành viên lọc theo chữ gõ, chọn → chèn
  "@Tên " và ghi `mentions` {uid, pos, len}.
- Nút Gửi mờ khi: ô trống và không có tệp; tài khoản không READY (title "Tài khoản chưa sẵn sàng");
  đang gửi tệp.
- Thanh trích dẫn: "↩ Trả lời **An**: đoạn chữ…" + ×; Esc huỷ trả lời.
- **Bẫy CSS đã gặp:** class tiện ích kiểu `.d-flex { display:flex !important }` đè `display:none`
  khi ẩn phần tử → thanh trả lời/khay tệp không bao giờ ẩn. Ẩn/hiện bằng thuộc tính `hidden` + CSS
  `[hidden]{display:none !important}`, KHÔNG dùng class `!important` cho display.

### 7.5 Màn Danh bạ

- Chip chọn **một** tài khoản ("Danh bạ của: [QD] [Beta]").
- Ô "Tìm trong danh bạ" (lọc tại trình duyệt, bỏ dấu), tab **Bạn bè (n)** / **Nhóm (n)**.
- Nút: Kết bạn (modal tra số điện thoại, lỗi hiện **ngay trong modal**), Tạo nhóm (modal: tên + chọn
  thành viên có ô tìm), Làm mới danh bạ (`refresh=1`).
- Khu "Lời mời kết bạn" (nếu có): ảnh, tên, lời nhắn, [Chấp nhận] [Từ chối].
- Danh sách ảo hoá đơn giản: chỉ render 100 dòng đầu + "Hiện thêm" (danh bạ có thể vài nghìn người).
- Trạng thái rỗng: "Chưa có bạn bè nào. Kiểm tra tài khoản đã Sẵn sàng và bấm Làm mới danh bạ."

### 7.6 Polling thông minh (thay cho realtime đẩy)

Mặc định dùng polling (PHP-FPM giữ kết nối SSE sẽ chiếm worker). Thuật toán:

```
state: versions{accountId: n}, inFlight{resource: bool}, abort{resource: AbortController}

pollChanges():                                   // nhịp chính, RẺ (chỉ đọc Redis)
  nếu document.hidden → dừng hẳn
  GET /api/chat/changes?accounts=…               (timeout 5s)
  với mỗi account có version tăng:
      đánh dấu cần tải lại danh sách của account đó
      nếu hội thoại đang mở thuộc account đó → tải lại tin của hội thoại đang mở
  delay = có thay đổi ? 3000 : backoff[i++]       backoff = [3000, 5000, 10000, 20000, 30000]
  setTimeout(pollChanges, delay)

khi có hoạt động (gửi tin, mở hội thoại, bấm làm mới, focus cửa sổ) → i = 0, gọi ngay
visibilitychange → hidden: clearTimeout; visible: gọi ngay 1 lần rồi nối lại nhịp
```

- Mỗi tài nguyên (danh sách theo tài khoản / tin của hội thoại đang mở / tìm kiếm) có cờ `inFlight`
  và `AbortController`: bắn request mới thì `abort()` request cũ; không bao giờ có hai request chồng
  nhau cho cùng tài nguyên.
- Chỉ poll hội thoại **đang mở**, không poll tất cả.
- Tải lại tin: gọi trang đầu (50 tin mới nhất) rồi **hợp nhất** theo `msg_id` vào danh sách đang có
  (giữ các trang cũ đã tải, giữ bong bóng optimistic chưa có `msg_id` thật).
- Tìm kiếm: debounce 300ms, rỗng → quay về danh sách thường.
- Trạng thái tài khoản (status) poll riêng 30 giây/lần cho popover và dải cảnh báo.
- Nếu sau này cần realtime hơn: SSE một endpoint đọc Redis pub/sub, chạy ở tiến trình riêng
  (không qua php-fpm) — chỉ làm khi polling chứng minh không đủ.

### 7.7 Màn Tài khoản Zalo (`/settings/accounts`)

- Thẻ thống kê: Sẵn sàng (n) · Chờ đăng nhập (n) · Lỗi (n).
- Ô "Tên tài khoản mới" + nút **Thêm tài khoản**.
- Bảng: Tên · Zalo (ảnh + tên Zalo + uid rút gọn) · Trạng thái (badge) · Người tạo · Lần cuối hoạt
  động · Thao tác [Mở phiên] [Đóng] [Đăng nhập lại] [Xoá] [Mở Chat].
- **Modal QR**: ảnh QR 240px, hướng dẫn "Mở Zalo trên điện thoại → biểu tượng QR → quét mã", đếm
  ngược hết hạn, khi đã quét hiện "Đã quét bởi **{tên}** — hãy bấm Đăng nhập trên điện thoại",
  hết hạn → nút "Lấy mã mới", READY → dấu ✓ xanh + tự đóng sau 1,5s + toast "Đã kết nối {tên}".
- Xoá: hộp thoại xác nhận yêu cầu gõ lại tên tài khoản; nêu rõ "Lịch sử sẽ được giữ lại và tự gắn lại nếu bạn đăng nhập lại đúng tài khoản Zalo này".
- Modal "điểm danh" khi đăng nhập: nếu có tài khoản RELOGIN_REQUIRED/ERROR → modal liệt kê, nút đi tới trang tài khoản.
- Admin: lọc theo người tạo, giao tài khoản cho nhân viên (multi-select), chuyển chủ sở hữu.

### 7.8 Token màu & kiểu chữ (giữ nhận diện hiện có)

```css
:root{
  --app-bg:#f8f5f8; --app-rail:#2b1648; --app-rail-soft:#5a2479;
  --app-brand-pink:#d92870; --app-brand-orange:#ff7a1a;
  --app-border:#e5dce8; --app-border-soft:#f2ecf5;
  --app-surface:#fff; --app-surface-soft:#fff9fc;
  --app-text:#201629; --app-muted:#746a7d;
  --app-accent:#c21d63; --app-accent-strong:#7f1649; --app-accent-soft:#fff0f6;
  --app-danger:#e11d48; --app-danger-soft:#fff1f2;
  --app-warning-soft:#fff8e1; --app-success-soft:#e8f7ee;
  --app-message-in:#fff; --app-message-out:#fff0f6;
  --app-shadow:0 18px 46px rgba(43,22,72,.08);
  --app-control-bg:#f7f4f8; --app-control-ring:rgba(194,29,99,.22);
}
```

Font hệ thống (`system-ui, -apple-system, "Segoe UI", Roboto, sans-serif`), cỡ 14px, bong bóng
14px/1.45, tên hội thoại 14px đậm 600, preview 13px màu `--app-muted`. Bo góc: bong bóng 16px,
thẻ 12px, nút 10px. Focus ring 3px `--app-control-ring`.

### 7.9 Responsive

- ≥ 1200px: 3 cột như sơ đồ.
- 768–1199px: rail 56px, cột giữa 300px.
- < 768px: một cột; danh sách hội thoại toàn màn, mở hội thoại → khung chat trượt vào, nút ← quay
  lại; rail thành thanh dưới cùng. Lề ngang 16px, không cuộn ngang.

### 7.10 Cấu trúc JS thuần (không framework)

```
public/zalo/chat.js       (IIFE, "use strict")
  const api = { get(url, {signal}), post(url, body|FormData), patch, del }   // fetch + CSRF + JSON + map lỗi
  const store = { accounts, activeAccountIds, conversations: Map<key,conv>, messages: Map<key,{items,hasMore,cursor}>,
                  selectedKey, drafts: Map<key,string>, pending: Map<clientId,msg>, versions }
  render functions: renderRail(), renderConversationList(), renderChatHeader(), renderMessages(), renderComposer()
  - render bằng <template> + cloneNode, cập nhật theo key (data-key) thay vì innerHTML toàn bộ để không mất cuộn/focus
  - mọi chuỗi từ server gán qua textContent; chỉ nội dung tin đã escape mới qua innerHTML (cho link/mention)
  event delegation trên container (click, contextmenu, dblclick, keydown)
  modules: poller, composer (paste/drop/files/emoji/templates/mentions), contextMenu, lightbox, toast
```

Mỗi tệp JS/CSS nạp kèm `?v={{ filemtime(...) }}` để trình duyệt lấy bản mới sau deploy.

---

## 8. PHÂN QUYỀN VÀ BẢO MẬT

### 8.1 Ranh giới phân quyền — gom ở ba chỗ, không rải `if`

1. `ZaloAccount::scopeVisibleTo(User $u)`: admin → tất cả (trừ xoá mềm); staff → `user_id = u.id`
   hoặc có dòng trong `zalo_account_user`.
2. Middleware `EnsureZaloAccountAccess` (`zalo.account`): đọc `{id}` từ route, 404 nếu không thấy
   trong `visibleTo` (404 chứ không 403 để không lộ tài khoản tồn tại). Gắn cho **cả nhóm**
   `zalo-accounts/{id}/*`.
3. API ngoài (nếu có) dùng đúng hàm `visibleTo` đó.

Chốt chặn: không tự hạ vai của chính mình; không hạ vai/xoá admin cuối cùng.
Lệnh khởi tạo: `php artisan user:create-admin --name= --phone= --password=` (gán luôn các tài khoản
Zalo chưa có chủ cho admin đầu tiên).

### 8.2 Bảo mật dữ liệu

- Credential: `Crypt::encryptString` (APP_KEY), bảng riêng, `$hidden`. Đổi APP_KEY = mất toàn bộ phiên
  (phải quét lại) → ghi rõ trong tài liệu vận hành.
- `zalo:ctx:*` trong Redis cũng mã hoá (chứa cookie + secret key).
- Log: che `cookie`, `imei`, `zpw_enk`, `secret`, nội dung tin (trừ khi bật cờ debug có thời hạn).
- CSRF: mọi `fetch` gửi `X-CSRF-TOKEN`; `SESSION_SAME_SITE=lax`, KHÔNG đặt `none`.
- Ảnh từ CDN Zalo: `referrerpolicy="no-referrer"`.
- Không có route debug trả HTML/payload thô ra ngoài.
- Upload: kiểm MIME thật (`finfo`), chặn đuôi Zalo cấm (`.exe`, `.bat`, `.apk`, `.js`, `.vbs`…).
- Rate limit Laravel: gửi tin 30/phút/người dùng, tra số điện thoại 20/giờ/tài khoản Zalo (giảm rủi ro bị khoá).

---

## 9. HIỆU NĂNG, LƯU TRỮ, VẬN HÀNH

### 9.1 Query nóng (PHẢI dùng index ở 3.5, kiểm `EXPLAIN` không có filesort)

- Trang tin: `WHERE zalo_conversation_id=? [cursor] ORDER BY sent_at DESC, id DESC LIMIT 51`.
- Đếm chưa đọc: `WHERE zalo_conversation_id=? AND direction='in' AND sent_at>?`.
- Tra quote: `WHERE zalo_account_id=? AND msg_id=?`.
- Sidebar: `WHERE zalo_account_id=? AND is_hidden=0 [cursor] ORDER BY last_message_at DESC, id DESC LIMIT 51`.

### 9.2 Giữ tối đa N tin / hội thoại (tuỳ chọn, cho quy mô lớn)

Khi `keep_per_conversation > 0`: sau mỗi lô ghi, dispatch `PruneConversationMessagesJob` (unique theo
conversation, `Cache::lock` 60s):
```php
do {
  $ids = DB::table('zalo_messages')->where('zalo_conversation_id', $cid)
         ->orderByDesc('sent_at')->orderByDesc('id')->offset($keep)->limit(1000)->pluck('id');
  if ($ids->isEmpty()) break;
  DB::table('zalo_messages')->whereIn('id', $ids)->delete();
} while ($ids->count() === 1000);
```
Không `DELETE WHERE sent_at < cutoff`. Dọn kèm `zalo_agent_sent_messages` cũ hơn 90 ngày.

### 9.3 Trần tệp đính kèm phải khớp nhiều tầng

| Nơi | Giá trị | Vai trò |
|---|---|---|
| `config/zalo.php` | 5 tệp / ảnh 5MB / video 15MB / tệp 15MB / tổng 20MB | nguồn sự thật |
| `php.ini` | `upload_max_filesize=20M`, `post_max_size=24M`, `memory_limit=384M`, `max_execution_time=180` | PHP nuốt request rỗng nếu vượt, **không báo lỗi** |
| nginx | `client_max_body_size 24M`, `fastcgi_read_timeout 180s` | nginx cắt trước khi tới PHP |
| blade → `window.ZALO_LIMITS` | nhúng từ config | chặn ngay ở trình duyệt |

Đổi trần → sửa đủ các nơi. Request rỗng bất thường (`$_FILES` trống mà Content-Length lớn) → trả lỗi
"Tệp vượt quá dung lượng máy chủ cho phép".

### 9.4 Giám sát

Trang health (admin): mỗi shard gateway (heartbeat, số phiên, RAM `memory_get_usage`), `LLEN zalo:ingest`,
mỗi tài khoản (trạng thái, `last_event_at`, số lần reconnect 1 giờ qua, lỗi gần nhất). Cảnh báo khi:
heartbeat mất > 60s, hàng đợi > 1000 trong 1 phút, tài khoản READY mà không có sự kiện > 6 giờ (nghi
"chết lặng"), tài khoản chuyển RELOGIN_REQUIRED.

### 9.5 Triển khai

- Supervisor: `zalo-gateway-0..M-1`, `zalo-consume`, `queue-zalo-login`, `queue-default`, `scheduler`.
- **zca-php ghim đúng một bản** trong `composer.json` (`"eric-sa/zca-php": "2.1.0"`, không `^2.1`) và
  commit `composer.lock`. Gói mới (v2.0.0 phát hành 02/11/2026, v2.1.0 thêm đồng bộ từ điện thoại
  03/11/2026), Zalo đổi giao thức thì gói đổi theo → nâng bản là một thay đổi có kiểm thử: đọc diff gói,
  chạy lại 4.7 trên tài khoản phụ, rồi mới deploy.
- Deploy: `php artisan migrate --force` (không fresh), `config:cache`, `supervisorctl restart zalo-consume queue-*`;
  gateway restart = mọi phiên đăng nhập lại bằng cookie (không cần QR) và xin tin tồn — chấp nhận được,
  nhưng tránh restart giờ cao điểm.
- Một tài khoản Zalo chỉ nên có **một** listener web đang chạy: dặn người dùng không mở Zalo Web/PC
  cùng tài khoản khi gateway đang nghe (sẽ bị đá mã 3000).
- Backup MySQL hằng ngày (`zalo_messages` không tái tạo được). Backup riêng bảng `zalo_credentials` (đã mã hoá) + APP_KEY ở nơi an toàn.

---

## 10. CẠM BẪY ĐÃ TRẢ GIÁ (đọc trước khi sửa)

| # | Bẫy | Cách đúng |
|---|---|---|
| 1 | Cộng dồn `unread_count` theo lô → gửi lại lô 3 lần thành 6 chưa đọc | Luôn đếm lại từ DB |
| 2 | `last_read_at = now()` → tin vừa đọc lại thành chưa đọc vì đồng hồ Zalo đi trước | `last_read_at = MAX(sent_at)` |
| 3 | Đọc tin để AI soạn trả lời cũng đánh dấu đã đọc | `markRead` mặc định tắt, chỉ UI bật |
| 4 | Tin AI gửi bị coi là "người đã xem" | Bảng `zalo_agent_sent_messages`, loại khỏi phép đếm |
| 5 | Đặt tên nhóm theo `sender_name` | Nhóm để trống, lấy từ `getGroupInfo` |
| 6 | Tên 1-1 lấy từ tin (zaloName) khác app (displayName) | Danh bạ luôn ghi đè, `custom_name` ưu tiên nhất |
| 7 | Tên tự đặt ghi vào `display_name` → bị đồng bộ đè | Cột `custom_name` riêng |
| 8 | Backfill kích hoạt AI trả lời câu hỏi tuần trước | `is_backfill` không trigger |
| 9 | Backfill thắp chưa đọc cả lịch sử | `markBackfillAsRead` cho hội thoại chưa mở |
| 10 | Lỗi worker = "không có gì ẩn" → hội thoại riêng tư bật ra | Lỗi giữ nguyên cờ cũ |
| 11 | Credential mồ côi làm hỏng nguyên lô ingest | Lọc account không tồn tại |
| 12 | Chỉ đóng phiên khi xoá tài khoản → hai phiên đá nhau mã 3000 | Xoá credential + lệnh `forget` |
| 13 | Gắn bước nhận lịch sử vào điều kiện "uid đổi" → kẹt vĩnh viễn | Chạy ở mọi lần báo trạng thái |
| 14 | SQLite cho subquery vào bảng đang DELETE, MySQL cấm (1093) | Test thêm trên MySQL |
| 15 | Trích dẫn chỉ bằng msgId → Zalo từ chối | Lưu `quote_payload` thô ngay lúc nhận |
| 16 | Nhắn nhóm chưa có bản ghi → mặc định `user` → Zalo từ chối | Mở từ danh bạ phải qua `contacts/open` |
| 17 | Định danh hội thoại phía client thiếu account → mở nhầm phiên | `accountId::threadId` |
| 18 | `json_encode` PHP escape Unicode/`/` khác JS → chữ ký HMAC lệch | Nếu có ký nội bộ: `JSON_UNESCAPED_UNICODE`, ký trên raw body |
| 19 | Giữ tệp chờ gửi khi đổi hội thoại → ảnh bay nhầm người | Xoá khay khi đổi hội thoại |
| 20 | `.d-flex !important` đè `display:none` | Dùng thuộc tính `hidden` |
| 21 | Hàng đợi trong RAM tràn khi import 337k tin → mất 326k tin | Backfill lớn đi đường có backpressure, không nhồi queue |
| 22 | Redis `allkeys-lru` xoá job đang chờ | `noeviction` |
| 23 | Ảnh nhận về dùng `att.dataUrl` (chỉ có ở tin vừa gửi) → `src="undefined"` | `dataUrl → url → thumb_url` |
| 24 | Tin ảnh kèm chữ: chữ nằm trong `title` của ảnh | Chuẩn hoá đưa vào `content` |
| 25 | Tin `group.poll`, `webchat` dạng object → Zalo từ chối trích dẫn | `quote_payload=null` ngay từ đầu |
| 26 | Tài khoản không có phiên sống bị loại khỏi mọi vòng xử lý mà không log | Gateway không có trần phiên; giám sát "chết lặng" |
| 27 | QR mode "web" làm Zalo báo lỗi khi kiểm tra session | Dùng chế độ PC + User-Agent Chrome 130/Windows (4.2); với zca-php PHẢI truyền `userAgent` vào `loginQR` (mặc định gói là Firefox) |

Bẫy riêng của zca-php (biết được khi đọc mã nguồn gói, chưa "trả giá" — giữ ở đây để không ai phải trả):

| # | Bẫy | Cách đúng |
|---|---|---|
| Z1 | `checkUpdate` mặc định bật → mỗi lần đăng nhập gọi `registry.npmjs.org` | `checkUpdate => false` trong `ZcaFactory` (4.3) |
| Z2 | `loginQR` không có callback → ghi `qr.png` ra thư mục làm việc | Luôn truyền callback, không gọi `saveToFile` (4.2) |
| Z3 | `selfListen` mặc định tắt → tin tự gửi từ điện thoại không về, mất tin `out` | `selfListen => true` |
| Z4 | Gọi `$api->listener->run()` cho từng tài khoản → kẹt ở tài khoản đầu | Một `Loop::run()` cho cả gateway (2.4) |
| Z5 | Gửi video/tệp từ tiến trình không có listener → lỗi; mở listener ở web → đá gateway (3000) | Video/tệp đi lệnh `send_files` qua gateway (5.10) |
| Z6 | Gọi API zca-php trong callback gateway "vì đã có fiber" → vẫn chặn mọi socket | Tra cứu phụ đẩy cho consumer/queue (2.4) |
| Z7 | `retryOnClose: true` → gói tự nối lại cả khi bị đá 3003 | `retryOnClose: false`, tự backoff (4.4) |
| Z8 | Đăng ký `custom()` hai lần trên cùng `Zca\API` → ném lỗi | Đăng ký một lần khi tạo API (4.6.2) |

---

## 11. KIỂM THỬ VÀ NGHIỆM THU

### 11.1 Unit test (không mạng, không DB thật)

- Không test lại mã hoá/giải mã frame — đó là việc của zca-php. Test **lớp bọc** của dự án.
- `MessageNormalizer`: dựng `Zca\Models\UserMessage`/`GroupMessage` từ `data` thô đã ghi lại một lần
  khi khảo sát (lưu `tests/Fixtures/zalo/` sau khi xoá nội dung nhạy cảm): tin chữ, ảnh 1 tấm, album,
  ảnh kèm chữ, sticker (đủ 4 dạng id), tệp, video, danh thiếp, link, tin nhóm có mention, tin có quote,
  tin tự gửi (`direction=out`, `thread_id` = người nhận), `quote_payload` = `data` nguyên vẹn.
- `ZaloContext`: `fromZca()` → `toArray()` → `toZcaApi()` khứ hồi đủ trường (cookie, `extraVer`,
  `loginInfo`), `Zca\API` dựng được mà không có request HTTP nào (Guzzle `MockHandler` không được gọi).
- `ZaloLoginQr`: giả lập chuỗi callback zca-php (Generated → Expired ×3 → Aborted; Generated → Scanned →
  Declined; … → GotLoginInfo) → đúng sự kiện 4.2 và đúng số lần gọi `retry`.
- `ZaloErrorTranslator`: `ZaloApiError` với từng `$zaloCode` đã biết → đúng mã nội bộ / `ZaloAuthExpired`.
- `ImageSize`: PNG/JPEG/GIF/WebP/BMP.

### 11.2 Feature test (SQLite in-memory + MySQL test cho SQL thô)

- Ingest: lô mới tạo hội thoại + tin; **gửi lại cùng lô 3 lần → vẫn N tin, unread không đổi**;
  tin cũ đến muộn không đẩy lùi preview; nhóm không bị đặt tên theo người gửi; backfill không trigger
  AI và không thắp unread cho hội thoại chưa mở; tài khoản không tồn tại bị bỏ.
- Chuỗi unread: nhận 2 tin → 2; mở (mark_read) → 0; tin mới → 1; mình trả lời → 0; AI trả lời → vẫn 1.
- Trích dẫn: tin có `quote_payload` gửi được; tin không có → 422 và **không gọi Zalo** (mock `ZaloApi`
  — interface của dự án, không mock `Zca\API`).
- Gửi video/tệp: web không gọi `ZaloApi`, chỉ RPUSH `send_files` đúng shard; reply quá hạn → `SEND_UNCERTAIN`.
- Phân quyền: staff A không đọc/gửi/xoá được tài khoản của staff B (404); admin được; không hạ admin cuối.
- Xoá + đổi chủ: tạo tài khoản, ingest, xoá mềm, tạo mới, báo READY cùng uid → dữ liệu chuyển sang id mới, không vỡ unique.
- Hội thoại ẩn: list/search/messages/contacts đều không lộ; lỗi đồng bộ giữ cờ cũ.

### 11.3 Kiểm thử với tài khoản Zalo thật (dùng tài khoản phụ)

1. Thêm tài khoản → QR hiện < 3s → quét → READY < 10s.
2. Nhắn từ điện thoại khác → tin hiện trên UI < 5s (polling 3s), huy hiệu đúng.
3. Gửi chữ có dấu, emoji, 5 ảnh, 1 PDF, 1 video 10MB → hiện đúng trên điện thoại.
4. Trả lời trích dẫn → trên điện thoại hiện đúng dạng trả lời.
5. Restart gateway → tự READY lại không cần QR; tin nhắn đến trong lúc tắt được bù qua tin tồn.
6. Đăng nhập Zalo Web cùng tài khoản ở trình duyệt khác → hệ thống chuyển RELOGIN_REQUIRED với lý do rõ.
7. Ẩn một hội thoại trên điện thoại → biến mất khỏi UI ≤ 60s.
8. Chạy 24 giờ: không rò rỉ RAM gateway (đo mỗi giờ), không có tài khoản "chết lặng".

### 11.4 Định nghĩa "xong" cho mỗi tính năng

Code + test xanh + đạt 7.1 + câu lỗi tiếng Việt cho mọi nhánh lỗi + có mục trong trang health nếu là
tiến trình nền + đã kiểm với tài khoản thật (ghi rõ phần chưa kiểm được).

---

## 12. LỘ TRÌNH TRIỂN KHAI CHO AGENT

Làm tuần tự; mỗi phase có cổng nghiệm thu, chưa qua không sang phase sau.

**Phase 0 — Khảo sát giao thức (bắt buộc trước khi viết gateway)**
- `composer require eric-sa/zca-php:2.1.0`; viết lớp bọc `app/Zalo/Protocol` (`ZcaFactory`,
  `ZaloContext`, `ZaloLoginQr`, `ZaloLoginCookie`, `ZaloApi`, `ZaloListener`) và các lệnh probe ở 4.7.
  Quét QR bằng tài khoản phụ, in `uid` + service map; đăng nhập bằng credential xuất từ worker cũ;
  mở listener, nhận `cipher_key`, nhận được 1 tin chữ.
- Cổng: nhận được tin thật qua `ZaloListener`, gửi được 1 tin chữ + 1 ảnh (web) + 1 tệp (gateway) bằng
  PHP; đã đo RAM/tài khoản và thời gian chặn loop khi đăng nhập lại và khi upload tệp.

**Phase 1 — MVP chat (F1–F6)**: migrations 3.1–3.5 + bảng phụ cần thiết; gateway + consumer; job QR;
màn tài khoản; màn chat (danh sách, đọc, gửi chữ + tệp, đa tài khoản, polling, optimistic); auth + phân quyền.
- Cổng: 11.3 bước 1–3, 5; test 11.2 phần ingest/unread/phân quyền.

**Phase 2 — Tương tác (F7–F10, F15)**: quote, mention, reaction, thu hồi, xoá, chuyển tiếp, danh bạ,
hồ sơ/ảnh, hội thoại ẩn, đổi tên, xoá hội thoại, tin tồn.
**Phase 3 — Mạng xã hội & công cụ (F11–F14)**: kết bạn, nhóm, sticker/danh thiếp/video/thẻ ngân hàng, thẻ, tin mẫu.
**Phase 4 — Tuỳ chọn (F16, phụ lục)**: đồng bộ từ điện thoại, AI, chiến dịch, OA.

---

## PHỤ LỤC A — Mã lỗi nội bộ → thông báo tiếng Việt

`ZaloErrorTranslator::message(string $code, ?string $detail)` — thêm mã mới PHẢI thêm dòng ở đây,
nếu không người dùng chỉ thấy câu chung.

| Mã | HTTP | Thông báo |
|---|---|---|
| `SESSION_NOT_READY` | 409 | Tài khoản Zalo chưa sẵn sàng. Hãy mở phiên hoặc quét QR ở trang Tài khoản Zalo. |
| `SESSION_STARTING` | 409 | Phiên Zalo đang khởi động, vui lòng thử lại sau vài giây. |
| `RELOGIN_REQUIRED` | 409 | Phiên Zalo đã hết hạn hoặc bị đăng nhập ở nơi khác. Hãy quét QR lại. |
| `ACCOUNT_NOT_FOUND` | 404 | Không tìm thấy tài khoản Zalo. |
| `CONVERSATION_NOT_FOUND` | 404 | Không tìm thấy hội thoại này. |
| `QUOTE_UNAVAILABLE` | 422 | Không trả lời được tin này: hệ thống không còn dữ liệu trích dẫn của nó. Hãy gửi như tin thường. |
| `ATTACHMENT_INVALID` | 422 | (chi tiết: đuôi bị Zalo cấm / quá dung lượng / ảnh hỏng) |
| `ATTACHMENT_UPLOAD_FAILED` | 502 | Tải tệp lên Zalo thất bại. Tin chưa được gửi. |
| `SEND_UNCERTAIN` | 504 | Zalo phản hồi quá lâu — tin có thể đã được gửi. Hãy kiểm tra trên hội thoại trước khi gửi lại. |
| `ZALO_REJECTED` | 502 | Zalo từ chối thao tác: {error_message từ Zalo}. |
| `ZALO_RATE_LIMITED` | 429 | Zalo đang giới hạn tần suất. Vui lòng chờ một lát rồi thử lại. |
| `RECALL_EXPIRED` | 422 | Đã quá thời gian cho phép thu hồi tin này. |
| `FRIEND_ACTION_FAILED` | 502 | (chi tiết từ Zalo) |
| `USER_NOT_FOUND` | 404 | Không tìm thấy người dùng Zalo với số này (số chưa dùng Zalo hoặc đã tắt tìm bằng số điện thoại). |
| `HIDDEN_CONVERSATION` | 403 | Hội thoại này đang bị ẩn trên Zalo. |
| `GATEWAY_DOWN` | 503 | Máy chủ kết nối Zalo đang khởi động lại. Vui lòng thử lại sau ít phút. |
| (mặc định) | 500 | Không thực hiện được thao tác trên Zalo. |

## PHỤ LỤC B — Module mở rộng (tóm tắt để biết chỗ nối)

- **AI tự trả lời:** bảng `ai_agents` (prompt, model, chế độ `draft`/`auto_send`), `ai_auto_replies`
  (`zalo_account_id`, `thread_id`, `thread_type`, `agent_id`, `last_msg_id`, `enabled`). Kích hoạt tại
  ingest (5.7) → `AutoReplyService::onIncomingMessage()` giành quyền bằng `UPDATE … SET last_msg_id=?
  WHERE id=? AND (last_msg_id IS NULL OR last_msg_id<>?)` (chống hai consumer cùng đẩy job) → `RunAutoReplyJob`.
  Tin AI gửi ghi `zalo_agent_sent_messages`. Không chạy cho backfill, hội thoại ẩn. Khuyến nghị bắt
  đầu ở chế độ "Tạo nháp".
- **Gửi hàng loạt theo thẻ:** `spam_campaigns` + `spam_campaign_targets` (chốt danh sách một lần,
  unique `(campaign, account, thread)`), job rải cách nhau `delay_seconds` (mặc định 5s ±20% nhiễu),
  đọc lại trạng thái chiến dịch trước mỗi lần gửi (tạm dừng/huỷ có hiệu lực ngay), tự dừng sau 5 lỗi
  liên tiếp, hàng đợi riêng `spam`. Rủi ro khoá nick cao — chỉ admin.
- **Zalo OA:** dùng OpenAPI chính thức (OAuth v4 + PKCE, webhook), dùng chung bảng hội thoại/tin với
  `zalo_accounts.channel='oa'`; rẽ nhánh ở đầu `ZaloSendService` (trước khi tra `quote_payload`), OA
  chỉ gửi tự do trong 7 ngày kể từ tin cuối của khách.
