# 06 — Lộ trình & câu hỏi mở ## Trạng thái hiện tại Cập nhật bởi skill `doc-sync` khi một phase bắt đầu/kết thúc. Một dòng mỗi phase; chi tiết (đã kiểm bằng gì, phát hiện, quyết định nhỏ) ở mục "Phase N — ghi chú" bên dưới. "Chưa thử thật" = mới kiểm bằng `FakeGateway`/client giả, chưa chạy trên Telegram thật. **0.1.x — đã phát hành `v0.1.1` (2026-09-28)** - [x] Phase 0 — Scaffold (2026-09-19) - [x] Phase 1 — Login, channels, tạo kênh (2026-09-19) - [x] Phase 2 — Copy + state + pause/resume (2026-09-20; đã chạy thật với kênh cho phép forward) - [x] Phase 3 — Filters + pushdown (2026-09-20; pushdown chưa đối chiếu trên Telegram thật, spike 3) - [x] Tái thiết luồng job (2026-09-20): bỏ job, `history`, delta, pause tại chỗ, phím `p`/`r`/`q` - [x] Phase 4 — Limiter & flood (2026-09-20; chưa gặp FloodWait thật) - [x] Phase 5 — `retry`, `status` (2026-09-20; chưa thử thật) - [x] Phase 6 — Reupload, tin đặc thù (2026-09-20; video tin đơn đã xác nhận thật). **Lỗi mở**: wizard `clone` không hỏi mode khi đã có `--src`/`--dst` — xem "Việc còn lại sau phase 6" - [x] Phase 6b — Analyze, tiến độ truyền file, trần tải trước, pool request (2026-09-20). Còn lại: relay theo part, chỉnh mặc định từ `flood_log` thật — xem "Kế hoạch tăng tốc" - [x] Phase 7 — TUI Rich, menu full-screen (Chặng 1–3, badge), `doctor`, đóng gói (2026-09-24) - [x] Phase 8 — Group, supergroup, forum, ánh xạ topic, đích khác loại (2026-09-25; **chưa clone một forum thật nhiều topic**) - [x] Phase 9 — Keyring (2026-09-25; chưa thử Credential Manager thật) - [x] Phase 10 — Xuất/nhập app data (2026-09-25; chưa thử chuyển máy thật) - [x] Phase 11a — Backup ra đĩa (2026-09-25; đã xác nhận thật) - [x] Phase 11b — Restore từ đĩa lên kênh (2026-09-26; xác nhận thật ở Đợt 4 của Phase 15b) - [x] Phase 12 — Docker chạy một lần, SIGTERM (2026-09-26; đã xác nhận thật) - [x] Phase 13 — CI + `release.yml` + Docker Hub + PyPI Trusted Publishing (2026-09-26/27; chạy thật lần đầu ở Phase 16) - [ ] Phase 14 — Phát hành đầy đủ. **Lát cắt winget** (2026-09-28): zip PyInstaller Windows đã lên Release `v0.1.1`; PR [`microsoft/winget-pkgs#442694`](https://github.com/microsoft/winget-pkgs/pull/442694) validation pass nhưng **chưa merge** (chờ người dùng ký CLA + moderator duyệt); job `winget-release` chờ PR đó merge + secret `WINGET_PAT`. PyInstaller Linux, APT/RPM, AUR **chưa làm**. Xem "Phase 14 — ghi chú" - [x] Phase 15a — Menu full-screen cho `backup`/`restore` (2026-09-27; đã xác nhận trên terminal thật) - [x] Phase 15b — Hardening toàn dự án (Đợt 1–3 xong 2026-09-27; **Đợt 4 xong 2026-10-12**, người dùng xác nhận phần thử thật). Xem "Phase 15b" - [x] Phase 16 — Phát hành 0.1.1 chính thức (2026-09-28): GitHub Release + `SHA256SUMS`, Docker Hub `0.1.1`/`latest`, PyPI — kiểm lại trực tiếp 2026-10-12 **0.2.0 — Inspect & Transform (đã duyệt hướng 2026-10-12; Phase 18a xong code 2026-10-12, Phase 19 đang làm theo lát cắt, 19a, 19b và 19b1 xong code 2026-10-13, 19c1 xong code và đã thử thật 2026-10-14, 19c2 xong code 2026-10-14 (album và tin thường đã thử thật; forward vào topic chưa), 19c3 xong code và đã thử thật 2026-10-14 (Phase 19 hết lát cắt), 18b xong code 2026-10-14 (chưa thử trên Telegram thật); chi tiết `07-inspect-transform.md`)** - [x] Phase 18a — `tgmirror inspect`, metadata/predicate mới, pre-flight, file selection, `--selection` (2026-10-12; đã thử trên Telegram thật phần lớn, còn vài mục nhỏ ở spike 14, xem "Phase 18a — ghi chú") - [x] Phase 19 — Transform khi sao chép (caption, hashtag ↔ topic, `topic_map`, reply, link nội bộ). **Làm theo ba lát cắt** (2026-10-13, xem "Phase 19 — ghi chú"): **19a xong code 2026-10-13** (chuỗi thao tác caption, `--transform`, `transform:` trong selection, nhớ theo cặp, pre-flight; **người dùng đã thử trên kênh thật 2026-10-13, mọi bước pass**); **19b và 19b1 xong code 2026-10-13** (hashtag → topic, `topic_map`, `hashtag_format`, `strip`, cờ `--topic-map`/`--topic-default`/`--strip-routing-hashtag`; **người dùng thử forum → forum bằng file transform 2026-10-13: chạy được** sau khi sửa lỗi khóa `topics` để trống bị lờ đi; các trường hợp còn lại chưa thử, xem "Phase 19 — ghi chú"); **19c1 (giữ reply: `reply: keep`, `--keep-replies`) xong code và đã thử trên Telegram thật 2026-10-14**; **19c2 (`forward_header: keep`, `--keep-forward-header`) xong code 2026-10-14; album và tin thường đã thử trên Telegram thật, forward vào topic chưa**; **19c3 (link nội bộ lùi: `links: rewrite`, `--rewrite-links`) xong code và đã thử trên Telegram thật 2026-10-14: viết lại thành công** — hết lát cắt của Phase 19 - [x] Phase 18b — Chỉ mục metadata cục bộ, `inspect --quick`, màn hình "Khám phá" (xong code 2026-10-14, sau spike 1 và một sửa phân loại media; **chưa thử trên Telegram thật**, xem "Phase 18b — ghi chú") - [ ] Phase 19d — Rate limit thích nghi: limiter theo từng khóa `(account, hành động, đích)`, phân loại FloodWait theo `X`, ngân sách cửa sổ trượt tự học thay cho `daily_cap` cố định (**duyệt hướng 2026-10-15; 19d1 (làn, sàn slow mode, `flood_log` đủ ngữ cảnh) xong code 2026-10-15, chưa thử trên Telegram thật; 19d2 (ngân sách tự học, cửa sổ trượt, `daily_cap` chỉ cảnh báo) xong code 2026-10-15, chưa thử trên Telegram thật**; người dùng chốt 2026-10-15 rằng 19d1 + 19d2 thuộc **0.2.0**; xem "Phase 19d — kế hoạch" và `05-chong-flood.md`, "Kế hoạch: rate limit thích nghi") - [~] Phase 19d4 — Thăm dò giới hạn có người dùng đồng ý: ngân sách học được chỉ giảm khi bị chặn và không bao giờ được thử vượt (lần 69, 70 tự dừng ở 1506 mà chưa biết hạn mức thật); thêm `ok`/`bad`/`checked_at` cho từng làn ghi, `--probe` và `--reset-limits` (cờ chạy một lần, không đổi cặp/filter), `tgmirror limits`, và câu hỏi ở đầu lần chạy khi giới hạn lâu chưa được kiểm chứng (**phần kèm 0.2.0 đã code 2026-10-17**: `ok`/`bad`, migration 7, trần 95%, `limits`, `limits reset`, `--reset-limits`; `--probe`, thăm dò và câu hỏi tự động chưa; xem "Phase 19d4 — kế hoạch" và "19d4 — đã cài" và `05-chong-flood.md`, "Kế hoạch: thăm dò giới hạn") **Chuẩn bị phát hành 0.2.0 (2026-10-14)**: `pyproject.toml`/`uv.lock` lên `0.2.0`, README đổi đoạn Status, `uv build` ra đúng `tgmirror-0.2.0` (wheel + sdist). **Tag đợi Phase 19d2** (người dùng chốt 2026-10-15: 19d thuộc 0.2.0). Sau đó, **còn lại là việc của người dùng**: push `main`, đợi CI xanh trên GitHub Actions (hai workflow cho tới nay chỉ chạy được thật ở Phase 16), tag `v0.2.0` (hoặc `v0.2.0rc1` trước, theo "Phase 13 — ghi chú": rc lên TestPyPI và không có `:latest`); `release.yml` kiểm tag khớp `version`. Chưa thử trên Telegram thật (không chặn, nêu trong README): màn hình "Khám phá" và `inspect --quick` (18b), forward giữ header vào topic (19c2). **0.3.0 — Thao tác tại chỗ (D10)** — *phát hành 2026-10-24 (xem nhật ký)* - [~] Phase 21 — Định tuyến tổng quát `topics.route`, cho cả topic lẫn hashtag (duyệt hướng 2026-10-18; `07-inspect-transform.md` mục 11). **Xong code 2026-10-18**: mô hình `route`, `hashtag_to_topic` thành cú pháp tắt, `strip: matched`, nhãn → hashtag cho đích không phải forum, bảng topic đích + mẫu tin không khớp trong `inspect --plan`; **bốn mục còn lại cũng xong code 2026-10-18** (cờ `--topic-skip/regex/pick/limit`, `inspect --dst-no-topics`, cột topic đích ở `inspect --by route` và màn Khám phá, bước wizard "Chia tin theo hashtag?"); **chưa**: thử trên Telegram thật (xem "Phase 21 — ghi chú") - [~] Phase 20 — `delete`/`edit`/`repost`/`undo`: plan → xác nhận → apply (kèm `edit` theo `msg_map`, `07` mục 11.4). **Lát 20.1 `delete` xong code 2026-10-18, đã thử thật 2026-10-23; lát 20.2 (lưới an toàn backup trước khi xoá, `O` trong `status`, mục "Xoá tin" trong menu, phím `d` ở Khám phá) xong code 2026-10-23 và đã thử trên Telegram thật 2026-10-24**; **lát 20.3 (`edit` + `undo`) xong code 2026-10-24 và đã thử trên Telegram thật cùng ngày (nhãn "đã sửa" có, thông báo không)**; **lát 20.4 (`repost`) xong code và đã thử trên Telegram thật 2026-10-24; thông báo của `--notify` chỉ kiểm được qua cờ `silent` phía server)**; **lát 20.5 (`edit --mirror`, sửa các bản sao của một cặp theo `msg_map`, kể cả link tiến) xong code và đã thử trên Telegram thật 2026-10-25**; Phase 20 hết lát cắt (còn mục menu "Sửa tin"/"Đăng lại") (xem "Phase 20 — ghi chú") - [x] Phase 20b — `tgmirror topics split/merge/delete/rename/close/reopen`: chia/gộp/xoá/đổi tên/đóng topic tại chỗ, dựng trên `repost`/`delete` (xong code và đã thử trên Telegram thật 2026-10-24, trên forum «Mediacenter» của người dùng với các topic `t20b-*` do mình tạo; xem "Phase 20b — ghi chú") - [x] Phase 17 — `tgmirror sync-changes`: đồng bộ edit/delete nguồn → bản sao ở đích, dựng trên máy của Phase 20 (xong code và đã thử trên Telegram thật 2026-10-24, trên kênh `mediacenter` riêng tư của người dùng và kênh test cũ `-1004414908395`; xem "Phase 17 — ghi chú") ## Lộ trình Thứ tự làm tiếp (18a, 18b, 19 đã xong code): **18a ✓ → 19 (19a, 19b, 19b1, 19c1, 19c2, 19c3 ✓) → 18b ✓ → 19d (19d1, 19d2 ✓; 19d4 một phần ✓) → 21 → 20 → 20b → 17 ✓ (17 làm trước 20b theo yêu cầu người dùng 2026-10-24)** (21 và 20b duyệt hướng 2026-10-18, thuộc 0.3.0) (giữ số phase cũ để các tham chiếu không lệch). Phase 14 (các kênh phân phối còn lại) làm xen khi cần, không chặn release nào. | Phase | Nội dung | Hoàn thành khi | |---|---|---| | 0–8 | Lõi: scaffold, login, copy A + state, filters, limiter, `retry`/`status`, reupload B, analyze/pool, TUI/menu/doctor, group/forum | Xem ghi chú từng phase | | 9–13 | Keyring, app data, backup/restore, Docker, CI/release | Xem "Kế hoạch Phase 9–16" | | 14 | Phân phối đầy đủ: PyInstaller (Windows ✓, Linux), winget, APT/RPM ký GPG, AUR | `winget install`, `apt`/`dnf install`, `uv tool install tgmirror` đều ra bản mới nhất | | 15a/15b | Menu cho backup/restore; hardening trước phát hành | ✓ | | 16 | Phát hành 0.1.1 | ✓ | | 18a | **0.2.0** — `inspect` (sống + thư mục backup), metadata/predicate mới (forward, reply, link, ...), pre-flight, file selection (`--save`/`--freeze`/`@last`), `--selection` cho `clone`/`backup`/`restore` | Inspect kênh thật rồi `clone --selection @last` sao chép đúng số tin inspect đã báo; pre-flight khớp số unit theo chiến lược của lần chạy thật | | 19 | **0.2.0** — Transform: chuỗi thao tác caption, hashtag → topic, `topic_map`, giữ reply, header forward, link nội bộ (lùi); cho cả `clone` và `restore` | Clone kênh thường sang forum với hashtag → topic: đúng topic, đúng thứ tự trong từng topic; restore cùng transform cho cùng kết quả | | 18b | **0.2.0** — Chỉ mục metadata, `inspect --quick`, màn hình "Khám phá" | Lọc lặp lại trên kênh 100k tin không gọi Telegram; từ Khám phá bấm `c` ra đúng wizard clone với filter điền sẵn | | 19d | **0.2.0** — Rate limit thích nghi: limiter theo làn, phân loại FloodWait theo `X`, sàn slow mode, ngân sách cửa sổ trượt có AIMD, `daily_cap` chỉ cảnh báo | `flood_log` đủ ngữ cảnh để phân tích (19d1 ✓ 2026-10-15); vượt `daily_cap` chỉ cảnh báo; một flood dài chỉ đặt/cắt ngân sách của đúng làn bị chặn, và lần chạy kế tiếp không vượt ngân sách đó, tiếp tục khi cửa sổ trượt nhả chỗ (19d2) | | 19d4 | Thăm dò giới hạn có người dùng đồng ý (người dùng chốt 2026-10-17: `tgmirror limits`, `limits reset`, `--reset-limits`, migration 7 và trần 95% của `bad` kèm 0.2.0; `--probe` và câu hỏi tự động sau 0.2.0) — `ok`/`bad`/`checked_at` theo làn, `--probe`, `--reset-limits`, `tgmirror limits`, câu hỏi khi giới hạn lâu chưa kiểm chứng | Một ngân sách bị kẹt dưới hạn mức thật nhích lên được qua vài lần `--probe` mà không cắt lại ngân sách sau một lần thăm dò hỏng; `--reset-limits` quên ngân sách của đích mà không hỏi; hai cờ không tạo cặp mới và không đổi filter | | 21 | **0.3.0** — Định tuyến tổng quát `topics.route`: điều kiện bằng filter, trích khoá bằng regex từ hashtag/caption/tên file/topic, `pick`, mẫu tên; một tin một topic; nhãn thành topic (đích forum) hoặc hashtag (đích khác); `hashtag_to_topic` thành cú pháp tắt (duyệt hướng 2026-10-18, `07-inspect-transform.md` mục 11) | Tin nhiều hashtag với `pick: last` và tên file trong caption vào đúng topic trên kênh thật; cùng file sang kênh thường cho đúng hashtag; transform 19b cũ cho đúng kết quả cũ | | 20 | **0.3.0** — `delete`/`edit`/`repost`/`undo` (D10), `ops`/`op_items` | Kill giữa `delete` 1000 tin rồi chạy lại: không sót, không xoá ngoài plan; `edit` rồi `undo` trả đúng text + định dạng gốc | | 20b ✓ | **0.3.0** — `topics split/merge/rename/close/delete` tại chỗ, dựng trên `repost`/`delete` của Phase 20: chia → topic mới đúng thứ tự gốc, xoá tin đã chuyển khỏi topic cũ; gộp → nối tin của topic sau vào cuối topic trước, rồi xoá topic sau (duyệt hướng 2026-10-18, `07` mục 11.3) | Gộp 2 topic nhỏ trên forum thử: không sót tin, không đụng topic khác; kill giữa chừng rồi chạy lại không đăng trùng | | 17 | **0.3.x** — Đồng bộ edit/delete nguồn → đích (`sync-changes`) | Sửa một tin ở nguồn rồi xoá một tin khác: `sync-changes` thấy đúng hai thay đổi đó, sau xác nhận sửa đúng một bản sao và xoá đúng một bản sao; chạy lại không còn gì để làm; `undo` trả lại chữ cũ ✓ (2026-10-24) | ### Tái thiết luồng job (2026-09-20) Lý do: `new` chỉ lưu một "job" rồi bắt người dùng gõ thêm `tgmirror run `; "chạy tay" phải nghĩa là gõ một lệnh như mọi lệnh khác (foreground, không chạy nền, không lên lịch, Ctrl+C là dừng), chứ không phải gõ hai lệnh. Người dùng cũng không muốn quản lý job: chỉ cần nhật ký các lần chạy, và chạy lại cùng cặp thì là delta. Các ghi chú Phase 2–4 dưới đây viết theo mô hình job (`new`, `run `, `--refilter`, `sync`); bản hiện hành là mục này và `02-cli-ux.md`, `04-state-checkpoint.md`. Đã có: - **`tgmirror clone`** (thay `new`): wizard hoặc cờ, xem trước, **một** câu xác nhận, rồi sao chép ngay. Bỏ `--name`, `--run/--no-run`, `JobExists`. - **Nhật ký + điểm kiểm tra**: bảng `jobs` tách thành `runs` (nhật ký, người dùng thấy qua `history`) và `mirrors` (con trỏ, filter nhớ, `dst_base_id` của một cặp; người dùng không thấy). Không có migration: dự án chưa phát hành nên schema mới thay thẳng `schema.sql`, DB cũ bị xóa. - **Chạy lại = delta; filter được nhớ**: không cờ lọc → dùng lại filter và chỉ lấy tin mới; filter khác → quét lại từ đầu bỏ qua tin đã sao chép (thay `--refilter`); `--no-filter` bỏ filter cũ. - **`run [n]`, `pause`, `stop`** giữ lại nhưng nhắm vào lần chạy (không còn id/tên job); `history [n] [--json]` mới. - **Pause tại chỗ**: tiến trình vẫn sống và giữ terminal, heartbeat vẫn ghi; `p`/`r`/`q` (phím thường vì VS Code nuốt Ctrl+P/Ctrl+R; `cli/keys.py`), Ctrl+C như cũ. Tất cả cùng đi vào `RunControl` để giao diện Rich sau này cắm vào. Các lựa chọn khi làm (không phải D1–D9; D5 đổi lý do, xem nhật ký quyết định): - **Vẫn phải có trạng thái theo cặp**: delta cần con trỏ, crash-safety cần `msg_map` ghi trước và `dst_base_id`; không suy ra được từ nhật ký mà không quét lại cả hai kênh. "Không lưu job" = không có thực thể để quản lý, không phải không có trạng thái. - **`q` thoát mã 0** (như `stop`), chỉ Ctrl+C thoát 130. - **Pause có hiệu lực ở ranh giới batch**, không cắt ngang lúc chờ FloodWait (stop thì cắt ngang được). - **Bộ đếm là của từng lần chạy**: con trỏ và `msg_map` là của cả cặp, nhưng `done/failed/skipped_filter` của `history` chỉ gồm việc lần đó làm. - **`sync`, `sync --all`, `jobs`, `rm` bỏ khỏi lộ trình** (không còn job để liệt kê hay xóa; `run` chính là `sync`). `retry` và `status` vẫn ở Phase 5. - **Run bị bỏ rơi** (heartbeat cũ hơn 2 phút) được ghi `failed('interrupted')` khi lần sau chạy cặp đó; `--force-takeover` ghi run cũ là `failed('taken_over')`. Chưa kiểm chứng (người dùng chạy tay): hai bộ đọc phím thật (`msvcrt` trên Windows Terminal/PowerShell, `termios` trên POSIX) chỉ được kiểm bằng script giả; pause/resume tại chỗ qua terminal thứ hai. ### `--fresh` — làm lại từ đầu (2026-09-20) Đã chạy một cặp nhưng muốn bắt đầu lại từ đầu (đã dọn đích, hoặc muốn bản sao thứ hai) thì trước đây không có cách: đổi filter vẫn bỏ qua tin đã sao chép, còn `--dst-new` là cặp khác. Người dùng chọn: tên **`--fresh`** (không phải `--new-run`: mọi lần `clone` vốn đã là một run mới), có cả ở `clone` và `run`, và wizard hỏi "Tiếp tục / Làm lại" với cặp đã có tin. - Quên **chỉ tiến độ** (`msg_map`, con trỏ), giữ filter và nhật ký; `--fresh --no-filter` bỏ cả filter. - Có hàng rào vì có thể trùng tin: một câu hỏi nêu số tin bị quên; `--yes` đồng ý; không terminal + không `--yes` thì mã 2. - Con trỏ lùi ở hai chỗ, cả hai trong `Store.start_run` (filter đổi, làm lại). - Để sau: chế độ kiểm tra/sửa (`--verify`: xem tin nào còn ở đích rồi chỉ sao chép lại tin thiếu). ### Phase 1 — ghi chú Đã có: `login`/`logout`/`whoami`, `channels` (`--search`, `--writable`, `--json`), `new` (bước 1–2 của wizard: chọn nguồn, chọn hoặc tạo đích), `TelethonGateway`/`TelethonAuth`, `--debug`, UI tiếng Việt/Anh (`TGMIRROR_LANG`). Tất cả test bằng `FakeGateway`/`FakeAuth`/`ScriptedPrompter` và stub client Telethon, không cần mạng. - **`new` chưa lưu job (lúc đó)**: phase 1 dừng sau khi chốt cặp nguồn/đích (và tạo đích nếu được yêu cầu, luôn có xác nhận hoặc `--yes`). Phase 2 đã nối `plan_endpoints`/`materialize` vào `create_job` và lưu job. - **Chưa có limiter (lúc đó; phase 4 đã làm cho `run`)**: `core/limiter.py` là phase 4. Các lời gọi phase 1 (`iter_dialogs`, `get_entity`, `CreateChannelRequest`, đăng nhập) là thao tác đơn lẻ do người dùng khởi động; FloodWait/PeerFlood được ánh xạ sang `FloodWait`/`PeerFlood`, in một câu và thoát mã 3, không retry. Luật 1 (mọi lời gọi qua limiter) chỉ thực sự áp dụng từ phase 4; không thêm lời gọi ghi hàng loạt trước đó. Phase 2 thêm lời gọi ghi hàng loạt đầu tiên (copy) nên có limiter tạm thời (ghi chú phase 2). - **Đã kiểm chứng với Telegram thật (2026-09-19, người dùng chạy tay trên Windows/PowerShell)**: `login`, `channels`, `new --src ... --dst-new ...` (kênh broadcast được tạo, có hỏi xác nhận). Còn chưa thử trên account thật: nguồn/đích supergroup, forum, group thường (nên `can_post`/`is_admin` suy từ entity, spike 4, mới xác nhận cho broadcast). Lưu ý PowerShell: `@name` phải đặt trong dấu nháy. ### Phase 2 — ghi chú Đã có: `store/` (`Store` trên SQLite: `jobs`, `msg_map`, `flood_log`; migration bằng `PRAGMA user_version`), `engine/` (`planner` → `batcher` → `copy` → `runner`, cùng `reconcile` và `jobs`), `TelethonGateway.iter_messages`/`copy_messages`/`last_message_id`, `core/limiter.py` (tạm thời), các lệnh `new` (lưu job; `--name`, `--mode`, `--batch-size`, `--run/--no-run`), `run` (`--force-takeover`), `pause`, `stop`. Tất cả test bằng `FakeGateway` cùng file SQLite thật trong `tmp_path`, không cần mạng. Tiêu chí "kill giữa chừng rồi resume không trùng/sót" được kiểm bằng `tests/integration/test_runner.py`: runner bị giết ngay sau write-ahead (trước lời gọi copy) hoặc ngay sau copy (trước commit), ở từng batch, rồi resume: mỗi tin xuất hiện đúng một lần ở đích, đúng thứ tự. Các lựa chọn khi làm (không phải D1–D9): - **Limiter tạm thời (phase 4 đã thay bằng AIMD đầy đủ)** (`core/limiter.py`): chỉ giãn cách batch (`min_delay` ± `jitter`, nghỉ dài mỗi `long_pause_every` tin). AIMD, `daily_cap`, `limiter_state` là phase 4 sau cùng giao diện `acquire(cost)`. - **FloodWait chưa được chờ (phase 4 đã chờ tự động; chỉ còn dừng job khi quá `max_auto_wait`)**: batch bị từ chối được xóa khỏi `pending` (Telegram không tạo gì), job thành `waiting_flood` + `resume_at`, ghi `flood_log`, thoát mã 3; `run` từ chối chạy lại trước `resume_at`. Chờ tự động (`max_auto_wait`) là phase 4. PeerFlood: job `failed(peer_flood)`, `run` từ chối trong 24h kể từ lúc đó. - **Một job cho mỗi cặp nguồn/đích**: `new` từ chối tạo job thứ hai cho cùng cặp (mã 2, chỉ tới job đã có), vì nó sẽ copy mọi thứ hai lần. - **`run` chạy được với job `done`**: nhặt tin mới sau `cursor_src_id`. Phase 5 chỉ thêm `sync` (và `sync --all`) bọc quanh cùng đường đó. - **Tin `None` từ `copy_messages`** (id đã bị xóa ở nguồn): sau một lời gọi thành công nghĩa là Telegram không tạo tin nào, nên ghi `failed` với `reason='not_copied'` (không phải "chưa rõ"; chỉ lời gọi bị ngắt giữa chừng mới cần reconcile). - **Batch bị `PerMessage`** (Telegram từ chối chính các id): xóa `pending` của batch rồi gửi lại từng unit một, để một tin hỏng không kéo theo cả batch. Unit đơn lẻ vẫn lỗi thì ghi `failed` cả unit (cả album). - **Lời gọi bị ngắt (`Transient`)**: giữ nguyên `pending`, job `failed('transient')`; lần `run` sau reconcile. - **`last_message_id`**: thêm vào protocol để `new` ghi `options.dst_base_id` (id tin mới nhất của đích lúc tạo job); reconcile chỉ đọc đích sau `max(dst_msg_id đã done, dst_base_id)`, không quét cả kênh đích cũ. - **Tiến độ** là dòng chữ thường (`ui/progress.py`, không ANSI, tối đa một dòng/5 giây). ~~TUI Rich có phím `p`/`q` là phase 7~~ — phím là `p`/`r`/`q` (ba phím, không phải hai), có từ đợt "Tái thiết luồng job"; TUI Rich (`ui/tui.py`) đã làm 2026-09-23, xem "Phase 7 — ghi chú". Ctrl+C lần một: xong batch hiện tại, lưu, thoát mã 130; lần hai: thoát ngay. - `MediaKind` thêm `geo`, `contact`, `game`, `invoice` cho khớp danh sách giá trị `media` của `03-filters.md`; loại lạ (dice, ...) tạm xếp vào `document`. Đã kiểm chứng (2026-09-20, người dùng chạy tay): `new`/`run` copy được từ một kênh cho phép forward. Cũng đã chạy đúng trên tài khoản thật: **album** (forward cả danh sách id giữ nguyên album ở đích, xong spike 2) và **kill giữa chừng rồi resume** (reconcile trên đích thật, không trùng/sót). Nguồn `noforwards` là group mà user không phải admin: `new` từ chối đúng như thiết kế (thông báo `err.source_restricted`, D3, mã 4), tức là `Chat.noforwards`/`Channel.noforwards` được nhận ra ở group. Chưa thử: nguồn `noforwards` mà user là admin (cảnh báo `noforwards_admin`, rồi `run` gặp `ForwardsRestricted` → mã 4 mới chỉ test bằng fake). Còn lại chưa kiểm chứng (người dùng chạy tay): - `forward_messages` trả `None` cho id đã xóa và ném `MessageIdInvalidError` khi mọi id đều đã xóa: đọc từ mã Telethon 1.45, chưa thử thật. - `get_input_entity(marked id)` trong `run` dựa vào cache entity trong file session (do `iter_dialogs` của `new`/`channels` ghi). Nếu thiếu, gateway báo `NoPermission` "not accessible": chạy `tgmirror channels` để làm mới. - Spike 7 (poll, quiz, ... khi forward) vẫn mở: phase 2 chuyển mọi tin, không tiền kiểm theo loại. ### Phase 3 — ghi chú Đã có: package `filters/` (`model`, `parser`, `matcher`, `pushdown`), `engine/preview.py`, `Skip`/`Batch.skipped` ở planner/batcher, `ServerFilter.until`, `TelethonGateway.iter_messages` với pushdown thật và `src_message` điền `hashtags`/`size`/`duration`/`mime`/`views`, `Store.replace_filters`, cờ lọc của `new` và `run --refilter`, `--preview`, `--no-pushdown`, bước 3 của wizard (`Prompter.checkbox`). Thêm dependency `pyyaml` (file `--filter-file`) và `regex` (timeout chống regex bùng nổ mà `re` không có). Tiêu chí "bộ test filter + so sánh pushdown với quét đầy đủ": `tests/unit/test_filter_*.py` và `tests/integration/test_pushdown_equivalence.py` (kênh ngẫu nhiên có album, 17 filter × 12 kênh; đã thử đột biến: bỏ hoàn thiện album hoặc bỏ lề id thì đỏ), cùng `tests/integration/test_runner_filters.py` (kill/resume, pause trong quãng dài không khớp, `--refilter`). Các lựa chọn khi làm (không phải D1–D9; chi tiết ở `03-filters.md`): - **Pushdown không được cắt album**: lề `ALBUM_MARGIN` cho ranh giới id/date; khi đẩy `media`/`search` thì planner hoàn thiện album bằng một lần đọc không lọc. Không đẩy `contains` (search theo từ, matcher theo chuỗi con) và `document`/`sticker`/`webpage`. - **Ngày → id ở gateway** (`get_messages(offset_date=..., reverse=True, limit=1)`), thêm `ServerFilter.until` để `--until` cũng giảm số tin phải đọc. - **Cursor và `skipped_filter`**: tin bị loại được cộng vào batch đang phát; batcher phát batch sau mỗi 500 tin bị loại (`FLUSH_AFTER`) nên quãng dài không khớp vẫn lưu tiến độ và nghe được pause/stop. Tin bị server loại (pushdown) không được đếm. - **`--refilter` là cách duy nhất đổi filter** vì mỗi cặp nguồn/đích chỉ một job và `rm` là phase 5; nó là chỗ duy nhất cursor lùi. - Sửa một lỗi phát hiện khi viết test: `size` được chuẩn hóa thành số byte trần nhưng số trần bị từ chối khi nạp, nên filter đã lưu không nạp lại được; nay lưu dạng `"B"`. Chưa kiểm chứng (người dùng chạy tay): tất cả hành vi thật của Telegram ở spike 3 (`search` + `filter` + `reverse` + `min_id`, `get_messages(offset_date, reverse)`, tokenize hashtag, entity hashtag của tin trong group). ### Phase 4 — ghi chú Đã có: `core/limiter.py` (AIMD, jitter, nghỉ dài, `daily_cap`, bucket đọc, giảm `batch_size` khi ≥ 3 flood/10 phút; đồng hồ và `sleep` tiêm vào), `engine/flood.py` (`FloodGuard`: `pace`, `write`, `reader`, xử lý FloodWait/SlowMode/PeerFlood, `Interrupted`), `Store.load_limiter_state`/`save_limiter_state` và `commit_batch(limiter=...)`, `DailyCapReached`, `FloodWait.slow_mode`, protocol `MessageReader`, khóa `[limits] read_delay`, cờ `run --wait`. Tiêu chí "test với FakeGateway kịch bản flood": `tests/unit/test_limiter.py` và `tests/integration/test_runner_flood.py` (FloodWait một lần → delay nhân đôi, batch gửi lại đúng một lần, không trùng `msg_map`; quá `max_auto_wait` → `waiting_flood`; PeerFlood; pause/Ctrl+C trong lúc chờ; daily cap qua nửa đêm bằng đồng hồ giả; đọc bị flood giữa chừng, kể cả giữa album). Đã thử đột biến (bỏ vị trí đọc tiếp, bỏ xóa `pending` khi `Interrupted`, bỏ lưu `limiter_state`, bỏ nhân đôi delay, bỏ throttle, bỏ daily cap, bỏ `max_auto_wait`, bỏ giới hạn 5 lần, bỏ giãn cách đọc): test đều đỏ. Các lựa chọn khi làm (không phải D1–D9; chi tiết ở `05-chong-flood.md`): - **`FloodGuard` thay vì bọc cả gateway**: runner vẫn gọi `pace` *trước* write-ahead (nên lúc ngủ giãn cách không có `pending`), rồi `write` bọc lời gọi copy; đọc đi qua `reader(gateway)` (một wrapper của `iter_messages`). Ghi và đọc cùng chia sẻ một `Limiter`. - **Đọc bị cắt bởi FloodWait thì đọc tiếp** từ id của tin cuối đã trao (`min_id = id đó`), vì đọc luôn tăng dần; album bị cắt giữa chừng vẫn nguyên vì planner ghép các tin cùng `grouped_id` liên tiếp. - **Đọc có bucket riêng** (`read_delay`, 0.5 s, nhân theo `delay/min_delay`); phần tra ngày → id của `--since`/`--until` tính là request đọc thêm. Việc khép kín "phase 4 phải đưa vào limiter" của phase 3. - **5 FloodWait liền cho cùng một lời gọi thì dừng job** (`MAX_FLOODS_PER_CALL`) thay vì ngủ vô hạn; `--wait` không bỏ giới hạn này. - **`--wait`** chỉ áp cho FloodWait, không cho daily cap (cap là ngân sách tự đặt: người dùng muốn chạy tiếp thì tăng `daily_cap`). - **Daily cap**: không gửi batch làm `sent_today` vượt cap, trừ batch đầu tiên của ngày; job `waiting_flood` với `fail_reason='daily_cap'` (cột `fail_reason` dùng cho lý do nghỉ); ngày tính theo giờ máy; bộ đếm theo account. - **SlowMode** giữ nguyên xử lý như FloodWait nhưng ghi `flood_log.kind='slow_mode'` (`FloodWait.slow_mode`). - **Chưa làm, để phase 7**: ~~đếm ngược động khi chờ (hiện một dòng thông báo)~~; ~~`status` hiển thị delay/flood 24h (phase 5)~~ — `status` đã làm ở phase 5 (`status.line_limiter`/`status.line_floods`); đếm ngược động thì **không làm** ở đợt TUI 2026-09-23 (ngoài mock của `02-cli-ux.md`, xem "Phase 7 — ghi chú"): lúc vào FloodWait vẫn chỉ có một dòng thông báo tĩnh (`run.flood_waiting`), như `LineReporter`. - **Không qua limiter** (một lần, do người dùng khởi động): các lệnh phase 1, `last_message_id` khi tạo job, `--preview`. FloodWait ở đó vẫn in một câu và thoát mã 3. Chưa kiểm chứng (người dùng chạy tay): mọi hành vi thật của Telegram. Chạy một job đủ lớn để chạm FloodWait thật, rồi xem `flood_log` (spike 6) trước khi tin vào các số mặc định; kiểm tra thêm rằng khi `FloodWait` ném ở giữa `iter_messages` thật thì Telethon không để lại trạng thái lạ và lần đọc lại từ `min_id` cho đúng tin kế tiếp. ### Phase 5 — ghi chú Đã có: `tgmirror retry [n]` và `tgmirror status [--json]`; `get_messages(src, ids)` ở `MessageReader`/`TelegramGateway` (`TelethonGateway`, `FloodGuard.reader`, `FakeGateway`); `planner.failed_units`/`Gone`; `Runner._failed_units` (nguồn `Unit` của lần chạy có `options.retry_of`); `engine/status.py` (`estimate`, `build_report`); `RunOptions.src_last_id`/`retry_of`/`for_pair`; `Store.count_failed`, `mark_gone`, `flood_count_since`; gợi ý `retry` khi một lần chạy kết thúc mà có tin lỗi. Không đổi schema (hai khóa mới nằm trong `options_json`, đã có sẵn chỗ cho khóa lạ). Tiêu chí "`retry` thử lại đúng các tin `failed`; `status` cho thấy tiến độ, tốc độ, ETA": `tests/integration/test_runner_retry.py` (đúng các tin lỗi, không quét nguồn, không đụng con trỏ/filter, album nguyên vẹn kể cả vắt qua ranh giới lô 100 id, tin đã xóa, kill trước/sau copy, FloodWait quá dài, stop, FloodWait lúc đọc theo id), `tests/unit/test_status.py`, `tests/unit/test_cli_retry.py`. Đã thử đột biến (bỏ giữ album qua lô, đổi công thức ETA, áp filter cho retry, không đặt tin đã xóa sang `skipped`, để khóa của lần chạy lọt vào mirror, gợi ý chạy tiếp bằng `run`, bỏ giãn cách đọc theo id, bỏ `run_id` ở `finish_batch`, bỏ khôi phục hàng `failed` khi hủy `pending`): test đều đỏ. Các lựa chọn khi làm (không phải D1–D9; chi tiết ở `02-cli-ux.md` và `04-state-checkpoint.md`): - **`retry` là một lần chạy riêng** (dòng trong `history`, pause/stop được, cùng `FloodGuard`/limiter), không phải một chế độ của `run`; đánh dấu bằng `options.retry_of` chứ không thêm cột (không cần migration: dự án chưa phát hành nhưng DB thật đã có dữ liệu clone, xóa nó chỉ để thêm một cờ là quá đắt). - **`retry n` = các tin `failed` có `run_id = n`** (chính là danh sách `history n`); tin lại lỗi chuyển sang lần retry mới, nên `tgmirror retry` (không số) thử tiếp. Không có `--all` (mọi tin lỗi của cặp): chưa ai cần, thêm sau nếu thiếu. - **Tin đã bị xóa ở nguồn** → `skipped` + `gone_from_source` thay vì để `failed` mãi (không ai sửa được, và `status` sẽ luôn báo lỗi). - **`status` chỉ đọc DB**: clone đang chạy giữ session nên không kết nối được từ terminal thứ hai. Vì vậy tổng cho tiến độ/ETA là id tin mới nhất của nguồn, ghi một lần khi lần chạy bắt đầu (`begin_run` thêm một `last_message_id(src)`, thuộc ngoại lệ "chuẩn bị" của luật 1). Tiến độ theo id là ước lượng thô (id có khoảng trống, filter nhảy nhanh); của retry thì chính xác. Tốc độ là trung bình từ lúc bắt đầu, ETA chỉ khi đang `running`. - **`status` không có số `n`**: chỉ xem lần đang chạy (hoặc gần nhất); chi tiết một lần cũ đã có ở `history n`. - **`get_messages` tối đa 100 id/lời gọi, phía gọi tự chia** (giống `copy_messages`); `FloodGuard` tính một request đọc cho mỗi lô. Lỗi phát hiện khi viết test (đã sửa): `insert_pending` ghi đè hàng `failed` thành `pending` và mọi đường hủy `pending` (reconcile thấy chưa gửi, FloodWait quá dài, stop khi chờ) **xóa** hàng đó. Với lần chạy thường không sao (con trỏ đưa tin trở lại), nhưng tin lỗi nằm dưới con trỏ nên một retry bị ngắt sẽ làm mất dấu tin đó hoàn toàn: không được sao chép, cũng không còn ghi nhận là lỗi. Nay hàng `pending` từng lỗi giữ `reason`/`run_id` cũ và quay về `failed` khi bị hủy (`04-state-checkpoint.md`, "Hủy `pending`"); `run_id` chuyển sang lần chạy mới khi batch kết thúc. Chưa kiểm chứng (người dùng chạy tay): `get_messages(ids=[...])` của Telethon với kênh thật (đọc mã 1.45: một slot mỗi id, `None`/`MessageEmpty` cho tin đã xóa, tự chia 100 id nhưng ta chia trước); forward một danh sách id thưa (album mà chỉ một số thành viên lỗi) có giữ nhóm album ở đích không; ETA trên kênh lớn có đủ tốt để tin. ### Phase 6 — ghi chú Đã có: `engine/strategy.py` (`Strategy`, `router`), `engine/reupload.py` (`plan_unit`, `send_unit`, `Window`, `Pipeline`, `UnsupportedMedia`), `Batch.strategy` (batcher cắt batch khi chiến lược đổi; unit tải lên lại luôn một batch riêng, phát ngay), protocol gateway `prepare`/`send_prepared`/`send_text` thay cho `reupload` (`TelethonGateway`, `FakeGateway`, `FloodGuard.reader(...).prepare`), viết lại caption (`rewrite_caption`, `strip_source_links`, UTF-16), `SrcMessage.quiz_unanswered`/`title`, `MessageResult.skipped` (+ `stats.skipped_unsupported`), năm khóa mới trong `RunOptions` (`caption`, `caption_text`, `reset_polls`, `ignore_unsupported`, `placeholder`) và `protected_ack`, cờ `clone --mode reupload`, `--caption`, `--caption-text`, `--reset-polls`, `--ignore-unsupported`, `--placeholder`, `--yes-i-administer-this-channel`, bước 4 của wizard, `[limits] prefetch`/`tmp_budget_mb` (thay `upload_concurrency`), dependency `hachoir`, và `begin_run` đọc lại nguồn trước lần chạy có thể tải lên lại. Tiêu chí "clone kênh thử có video lớn": chưa thử (cần Telegram thật). Bằng chứng thay thế: `tests/integration/test_runner_reupload.py`, `tests/unit/test_reupload.py`, `tests/unit/test_telethon_reupload.py`, `tests/unit/test_cli_reupload.py`. Người dùng chọn phạm vi trước khi làm: đủ theo lộ trình (lõi + tin đặc thù + `--caption`), và "uploader song song" là **pipeline tải trước** (tải unit kế trong lúc tải lên unit hiện tại), không phải nhiều kết nối kiểu FastTelethon. Các lựa chọn khi làm (không phải D1–D9; chi tiết ở `01-kien-truc.md`, `02-cli-ux.md`, `04-state-checkpoint.md`): - **Mỗi unit tải lên lại là một batch.** Một crash chỉ để lại đúng một unit `pending` nên reconcile so được; album vẫn nguyên. Giá là mỗi unit một lần `pace` (giãn cách 2 giây như mọi lần ghi): với ảnh nhỏ thì chậm hơn chiến lược A rất nhiều, chấp nhận vì reupload vốn dành cho việc mà A không làm được. - **Chỉ nửa đọc chạy trước** (`prefetch`, mặc định 1, tối đa `prefetch + 1` unit và `tmp_budget_mb` trên đĩa). Việc gửi vẫn tuần tự, đúng thứ tự (D4), một lời gọi một lúc. Lần chạy chỉ forward không đi qua pipeline (đọc trực tiếp như trước). - **Chưa có delay theo dung lượng** dù `05-chong-flood.md` từng hứa: không có số liệu để chọn hệ số. Sẽ xét khi có `flood_log` thật (spike 6). - **Tin không hỗ trợ: dừng ở tin đầu tiên gặp** khi không có `--ignore-unsupported`/`--placeholder` (thay cho thiết kế cũ "xem trước đếm số tin không hỗ trợ rồi hỏi"): không quét cả nguồn trước, tiến độ được giữ, chạy lại `clone` với cờ thì đi tiếp. Poll/quiz không có `--reset-polls` thì bị bỏ kèm cảnh báo (đúng thiết kế cũ) và không cần cờ nào khác. Delta không nhặt lại tin đã bỏ. - **`--caption` chỉ đổi caption của tin media**; `append` chỉ cộng vào caption đã có; `--mode copy` + `--caption` khác `keep` là lỗi mã 2 (forward không sửa được); `--mode auto` chỉ tải lên lại những unit có caption. Không dùng `drop_media_captions` của forward: `none` cũng đi đường tải lên lại để có một đường duy nhất. - **Cờ của chiến lược B chỉ đi với `--mode reupload`** (ở `auto` không có gì để bỏ qua nên cờ vô nghĩa và bị từ chối). - **D3: xác nhận của user là của riêng user.** `--yes` không thay được `--yes-i-administer-this-channel`; đó là điểm khác với mọi câu hỏi xác nhận khác. (Bản đầu từ chối nguồn cấm lưu nội dung mà tài khoản không phải admin bất kể cờ; **đã đổi cùng ngày**, xem nhật ký quyết định: có cờ thì cho qua, kèm cảnh báo trách nhiệm.) Lỗ hổng phát hiện khi thiết kế: `run`/`retry` không đi qua `plan_endpoints` nên một cặp đã clone bằng reupload sẽ tiếp tục tải nội dung xuống dù nguồn vừa bật cấm lưu (user không phải admin) → `begin_run` đọc lại nguồn (một request chuẩn bị) trước mọi lần chạy có thể tải lên lại. - **Bước 4 của wizard**: luôn hỏi mode (`auto`/`copy`/`reupload`), rồi (trừ `copy`) một câu có/không mặc định không cho caption và tin không sao chép được, để clone thường chỉ trả lời hai câu nhanh; nguồn cấm lưu nội dung bỏ câu mode (chỉ còn tải lên lại). Lúc đầu mode chỉ nằm sau câu có/không và thiếu `copy`; người dùng yêu cầu đưa ra thành bước riêng (2026-09-20). Mỗi câu hỏi mới làm lệch các test wizard cũ (chúng viết sẵn danh sách câu trả lời và chỉ số `select_labels`): đã cập nhật. - **Album qua `send_file([...])` cần `hachoir`**: Telethon gửi mọi file trong album với cùng tùy chọn và đọc duration/w/h từ file; tin đơn thì truyền thẳng `attributes` của tệp gốc. Nếu thấy video trong album mất thông tin, đường thay thế là dựng `InputMediaUploadedDocument` từng tin rồi `SendMultiMediaRequest` (mức thấp, chưa làm). - Placeholder có thể bị đăng trùng một dòng khi crash đúng lúc đăng (reconcile không so được text với game); chấp nhận (ưu tiên "không sót"). Lỗi người dùng gặp khi thử thật (2026-09-20, đã sửa): **video reupload ra thành tệp thay vì video**. Nguyên nhân: gửi `force_document=True` cùng thuộc tính của tệp gốc, nhưng Telethon đổi nó thành `force_file` trong `InputMediaUploadedDocument` nên Telegram hiện mọi thứ như tệp; giả định ban đầu ("thuộc tính giữ nó là video") sai và một test của tôi còn khẳng định chính hành vi sai đó. Nay chỉ tệp vốn là tệp thường mới bị ép; video/GIF/video tròn/nhạc/voice/sticker không, album nhạc/video cũng không, video thường thêm `nosound_video=True`. Bài học: stub client chỉ kiểm được tham số ta truyền, không kiểm được Telegram hiểu nó ra sao; cần thử thật (mục "Chưa kiểm chứng" dưới vẫn đúng cho những chỗ còn lại). Lỗi phát hiện khi viết test (đã sửa): (1) `stop` trong lúc unit kế đang tải khiến lần chạy kết thúc `done` thay vì `stopped` (chờ bị cắt bằng cách kết thúc luồng thay vì ném `Interrupted`); (2) hủy pipeline giữa lúc `queue.put` làm rò file của unit vừa tải xong và giữ chỗ trong `Window`; (3) khi kiểm tra đột biến, một đột biến làm task tải nền chết mà không trao lỗi khiến consumer chờ hàng đợi **vô hạn** (test không có timeout, script cũng không): `Pipeline` nay chờ cả task nền (`_next`) và báo lỗi/hủy của nó thay vì chờ mãi, thêm timeout cho từng test (`pytest-timeout`, 60 giây) và viết lại `scripts/mutation_check.py` để chạy trên bản sao tạm, có timeout. Kết quả `scripts/mutation_check.py` (người dùng chạy trong terminal VS Code, 2026-09-20): **25/25 đột biến bị phát hiện** (D3, thứ tự và tách batch, dọn file, dừng khi đang tải, task tải chết, caption/UTF-16/`parse_mode`, placeholder). Lần chạy đầu sót một: xóa việc dọn thư mục tạm ở *đầu* lần chạy vẫn xanh vì `finally` cuối lần chạy cũng dọn; test nay kiểm file cũ đã mất ngay lúc `prepare` đầu tiên. Bộ đột biến này chỉ phủ chiến lược B và D3, không phủ code phase 1–5. Chưa kiểm chứng (người dùng chạy tay, trên kênh thử có video lớn): mọi hành vi thật của Telegram. Cụ thể: tải media của nguồn cấm lưu nội dung bằng tài khoản admin có được không; `send_file(attributes=..., force_document=True)` có ra video/voice/sticker đúng loại thay vì tệp thường; album qua `hachoir`; ảnh bìa video (`thumb=`); `send_message(file=message.media)` cho poll/location/contact/dice; `results.results` có thực sự cho biết quiz đã trả lời; `message.chat.username` có mặt để `strip-links` nhận ra nguồn; tên tệp `download_media` trả về khi truyền đường dẫn `.part`; thời gian chờ và FloodWait khi upload file lớn (spike 6, spike 7, spike 8 vẫn mở). #### Việc còn lại sau phase 6 - **Lỗi mở: wizard `clone` không hỏi mode tải lên lại** (người dùng báo 2026-09-20, chưa điều tra; để phiên sau). Bước 4 (`wizard.pick_strategy`) được thiết kế để luôn hỏi mode, nhưng chỉ chạy khi `asked` đúng: wizard phải hỏi cả nguồn lẫn đích (không có `--src`, hoặc không có `--dst`/`--dst-new`), không có `--yes`, và chưa có cờ nào của bước này (`--mode`, `--caption`, ...) (`cli/commands/clone.py`). Nếu người dùng chạy `clone` với `--src`/`--dst` (hoặc `--yes`) mà vẫn muốn được hỏi thì bước này bị bỏ qua; nếu chạy `tgmirror clone` trần mà vẫn không thấy câu hỏi thì là lỗi thật. Việc cần làm: tái hiện cả hai cách chạy, rồi quyết định có nên hỏi mode dù đã có `--src`/`--dst` (giống bước filter, vốn cũng bị bỏ qua khi có cờ) hay chỉ sửa tài liệu, và thêm test cho đường wizard đã chạy đúng cách người dùng chạy. - Các mục "Chưa kiểm chứng" của phase 6 ở trên (trừ video tin đơn): album video qua `hachoir`, nhạc/voice/GIF/sticker, ảnh bìa, `--caption`, poll/location/contact, nguồn cấm lưu nội dung bằng tài khoản không phải admin, FloodWait khi upload lớn. ### Phase 6b — ghi chú Yêu cầu của người dùng (2026-09-20): cải thiện tốc độ tải xuống/lên và bước analyze, cần cho việc hiện tiến độ ("có bao nhiêu item cần làm" và tiến độ nhỏ của từng file tải xuống/lên). Sau một vòng brainstorm người dùng chốt: - **Analyze chỉ đếm số tin, chạy mặc định.** Dung lượng biết sau, từng file, lúc thực hiện. Không quét trước, không "scout" nền. - **Không cần IPC**: mỗi terminal là một process; `status` từ terminal khác chỉ đọc DB (không có tiến độ từng file, chỉ có "x / tối đa y"). - **Nhiều file cùng lúc được, miễn không vượt trần request**: số request dùng theo dung lượng file (nhỏ dùng ít, lớn dùng nhiều); tải xong file nào thì tải lên ngay trong lúc tải file kế. Album dùng chung ngân sách request trong một unit. Trần kết nối mặc định khoảng 4 rồi đo. Không hoãn nhiều kết nối (đảo lại lựa chọn "chỉ pipeline tải trước" của phase 6, xem nhật ký quyết định). - **Tải nhanh hơn gửi thì không được nổ RAM/đĩa**: cần trần cứng cho việc tải trước. - Cho phép mở spike (gửi bằng tham chiếu file, tốc độ nhiều request/kết nối, số đếm) trên kênh thử; người dùng chạy tay. Đã có: `TelegramGateway.count` (Telethon: một `messages.search`; `FakeGateway`; `_GuardedReader.count` không pace), `Runner._analyze` + `Store.set_total` + `RunOptions.total_items` + `Run.handled`/`already_done` + `Batch.already`, thông báo `analyzed`/`cap_days`, `status` tính theo `total_items` (dòng "Cap ngày", khóa JSON `total_items`/`handled`/`left`/`cap_rest_days`), `OnTransfer`/`TransferPhase` ở gateway (`prepare`, `send_prepared`), `engine/transfer.py` (`TransferTracker`, `Transfer`), `Reporter.transfer`, `LineReporter` (dòng "x/y tin" và dòng cho file ≥ 8 MB), `reserve_size`/`UNKNOWN_SIZE`/`Window.grow`, ba script spike (`scripts/spike_count.py`, `spike_reference.py`, `spike_throughput.py`). Chi tiết cơ chế ở `01-kien-truc.md` ("Analyze và tiến độ"), `02-cli-ux.md`, `04-state-checkpoint.md`, `05-chong-flood.md`. Kiểm bằng `tests/integration/test_runner_analysis.py`, `tests/unit/test_transfer.py`, `tests/unit/test_telethon_transfer.py`, các ca mới ở `test_status.py`, `test_reupload.py`, `test_runner_reupload.py`. Các lựa chọn khi làm (không phải D1–D9): - **`count` không qua `pace_read`** để không làm đổi nhịp đọc của mọi lần chạy (trước đó lần đọc đầu tiên đi ngay): một lời gọi mở đầu lần chạy, cùng loại với các lần đọc chuẩn bị. FloodWait của nó vẫn qua `FloodGuard`. Hệ quả là phép đếm cộng thêm một request (vài request nếu có ngày) vào mỗi lần chạy. - **Tổng là cận trên, được chặn bằng khoảng id** (`min(count, src_last_id - min_id)`), vì chưa biết Telegram có áp `min_id`/`max_id` khi tính `count` hay không. Lỗi Telegram ngoài FloodWait/PeerFlood của phép đếm không làm hỏng lần chạy. - **`already_done`**: tin vượt qua vì cặp đã có (đọc lại sau khi đổi filter) được đếm là đã xử lý, không thì phần trăm đứng yên. Lần chạy đầu và delta không bị ảnh hưởng. - **Pace không đổi** ở đợt này: `Limiter.acquire` vẫn ngủ cứng `delay × jitter` trước mỗi lần ghi, và write-ahead vẫn trước lời gọi `send_prepared`. Đổi hai chỗ đó là quyết định về crash-safety, chưa làm (xem dưới). - **Tiến độ album** lấy từ callback của Telethon (đếm theo file, có phần thập phân), đổi ra byte theo tổng dung lượng các file; dưới id tin đầu của album. Chưa kiểm chứng (người dùng chạy tay): `messages.search` `limit=1` có trả `count` đúng khi có `min_id`/`max_id`/filter không (`spike_count.py`); `progress_callback` của Telethon với file lớn và album (cỡ callback, có chạy trong lúc `send_file` không); mọi số tốc độ. #### Gửi bằng mã file — đã làm (2026-09-20) Sau spike 11 (video, tệp, album 6 video 115–490 MB, nguồn không cấm lưu nội dung) tôi làm phạm vi đã đề xuất; người dùng không phản đối và tiếp tục chạy spike. Phạm vi: chỉ `--mode auto` đổi caption trên nguồn không cấm lưu nội dung và unit toàn file; `--mode reupload` không đổi (đó là điều người dùng chọn); nguồn `noforwards` (kể cả đã tuyên bố theo D3) giữ đường tải xuống rồi tải lên vì chưa có số đo (đã đo 2026-09-21: Telegram từ chối, xem "Kết quả hai spike" ở phần Pool request). Có chuỗi lùi (đọc lại một lần, rồi tải xuống rồi tải lên). Cơ chế ở `01-kien-truc.md` ("Gửi bằng mã file"). Đã có: `Strategy.REFERENCE`, `router(..., by_reference=)`, `has_files`, `MessageReader.fetch`, `TelegramGateway.send_by_reference` (Telethon, `FakeGateway`, `_GuardedReader.fetch`), `send_unit_by_reference`, `RunOptions.src_protected` (do `begin_run` ghi), thông báo `reference_fallback`, tests ở `test_runner_reupload.py`, `test_reupload.py`, `test_telethon_reupload.py`. **Chưa thử trên Telegram thật** ngoài spike: caption/entity trên tin gửi bằng mã, ảnh bìa video, `FILE_REFERENCE_EXPIRED` thật (sau bao lâu), nguồn `noforwards`. Thứ tự ghi trong bản kế hoạch dưới đây, bước 4, nay đã xong. #### Kết quả `scripts/mutation_check.py` (người dùng chạy, 2026-09-20) 26/29 đột biến bị bắt; 3 bị bỏ qua vì mẫu không còn khớp sau khi mã đổi (`check_source` trả về `bool`, batcher cắt theo `is not Strategy.COPY`), không phải vì test thiếu. Đã sửa ba mẫu, thêm 13 đột biến cho phase 6b (D3 với gửi bằng mã file, làm mới tham chiếu, lùi về tải xuống, ngân sách đĩa, số đếm, `already_done`, pool: giảm ngân sách, nuốt FloodWait, hủy worker, file dở) và thêm các file test mới vào danh sách chạy; script được kiểm là mọi mẫu khớp đúng một lần (chưa chạy lại các đột biến mới). Nhắc lại: mỗi lần đổi mã mà script dựa vào, mẫu có thể lệch, nên chạy `--list` và đọc dòng `SKIPPED`. #### Pool request — đã làm (2026-09-20) Người dùng yêu cầu làm bước kế sau khi commit `ba576f8`. Số đo spike 12 quyết định thiết kế: tải xuống **một kết nối, nhiều request đang bay**; tải lên **2–3 kết nối**; trần tổng thấp và tự lùi vì 16 request trên 3 kết nối đã bị 429 ở tầng truyền. Đã có: `core/pool.py` (`RequestBudget`, `run_parts`), `TransportPressure`, `TransferSettings` và các hàm `_download_parallel`/`_upload_parallel`/`_request`/`_upload_senders`/`aclose` trong `telethon_gateway.py`, khóa `[limits] max_requests`, `upload_connections`, `pool_min_mb`; kiểm bằng `tests/unit/test_pool.py` (thuần) và `tests/unit/test_telethon_pool.py` (client giả trả `GetFileRequest`/`SaveBigFilePartRequest` từ bộ nhớ). Cơ chế ở `05-chong-flood.md` ("Pool request"). Các lựa chọn khi làm (không phải D1–D9): - **Không đổi pace, write-ahead hay crash-safety**: phần tải lên vẫn nằm trong `send_prepared` (sau write-ahead và `pace`), chỉ nhanh hơn. Hai việc cần duyệt riêng (đẩy byte tách khỏi đăng tin, pace theo deadline) **chưa làm**. - **Mặc định bật** (`max_requests = 4` sau lần chạy thật đầu tiên, xem trên); tắt bằng `0`. Chỉ tin đơn là tài liệu/video ≥ 10 MB dùng pool để tải lên (API big-file; album và ảnh giữ `send_file` của Telethon); tải xuống dùng pool cho mọi tài liệu ≥ `pool_min_mb`. - **Ưu tiên**: tải lên (số 0) trước tải xuống (số 1) khi tranh slot; gateway chưa biết thứ tự unit nên chưa ưu tiên theo unit. - **FloodWait giữa chừng làm lại file từ đầu** (chưa nhớ part đã xong); file dở luôn bị xóa khi lỗi để không giữ đĩa. - Dùng API private của Telethon (`_call`, `_borrow_exported_sender`, `_sender`, `_get_dc`, `_connection`): có thể vỡ khi nâng cấp Telethon (test bằng client giả không bắt được). **Chưa kiểm chứng trên Telegram thật** (người dùng chạy tay, cần một `clone --mode reupload` với video lớn): (1) video đăng từ `InputFileBig` vẫn là video (không thành tệp), có streaming và ảnh bìa (đã kiểm offline: `client._file_to_media(InputFileBig, attributes=[video], mime_type=..., nosound_video=True)` ra `InputMediaUploadedDocument` với `force_file=False` và thuộc tính video, cùng kết quả như khi truyền đường dẫn; còn thiếu là Telegram hiển thị ra sao); (2) tốc độ thật và không có 429 khi tải xuống và tải lên chạy cùng lúc dưới ngân sách 8; (3) tải xuống từ DC khác DC nhà; (4) file gần 2 GB. Chưa làm: ghi phản kháng tầng truyền vào `flood_log`. #### Nâng cấp Telethon Telethon được **ghim đúng một phiên bản** (`telethon==1.45.0` trong `pyproject.toml`, `uv.lock`, và `TELETHON_CHECKED` trong `core/telethon_gateway.py`), vì pool request và đường tải lên lại dựa vào phần bên trong mà Telethon không hứa giữ: `TelegramClient._call`, `_borrow_exported_sender`, `_return_exported_sender`, `_sender`, `_get_dc`, `_connection`, `_log`, `_proxy`, `_local_addr`, `_file_to_media`, `MTProtoSender(auth_key, loggers=)`, `InvalidBufferError.code`, cách `send_file` dựng media video từ `InputFileBig`. Các test dùng client giả không bắt được việc chúng đổi, nên `tests/unit/test_telethon_pin.py` bắt thay: nó **đỏ** nếu phiên bản cài đặt khác `TELETHON_CHECKED`, nếu `pyproject.toml` không ghim đúng phiên bản đó, nếu `telethon_gateway.py` chạm vào thêm một thành viên private mới của client (phải thêm vào danh sách trong test), nếu một thành viên private hay chữ ký đã biến mất, và nếu `send_file` từ một `InputFileBig` không còn dựng media video đúng (không ép thành tệp, giữ thuộc tính video và `nosound_video`). Checklist mỗi lần nâng cấp (làm theo thứ tự, không bỏ bước): 1. Đọc changelog Telethon giữa hai bản, tìm những thay đổi ở danh sách trên, ở `send_file`/`download_media`/`iter_messages`/`forward_messages` và ở xử lý flood. 2. Đổi ghim: `pyproject.toml` (`telethon==`), chạy `uv lock`, đổi `TELETHON_CHECKED`. 3. `uv run pytest` — `test_telethon_pin.py` chỉ ra chỗ nào của bề mặt private đã đổi; sửa adapter ở `telethon_gateway.py` (và mở rộng test) trước khi làm tiếp. 4. `python scripts/mutation_check.py` (terminal của người dùng): mọi đột biến phải bị bắt. 5. Chạy lại các spike với tài khoản thật: `spike_count.py` (số đếm theo vị trí), `spike_throughput.py download|upload|both` (tốc độ, không 429), `spike_reference.py` (đơn và `--album`). 6. Chạy tay một `clone` nhỏ: `--mode reupload` với video ≥ 10 MB (video vẫn là video, có streaming và ảnh bìa; đó là điều một stub không kiểm được), `--mode auto --caption append`, một album, và một lần Ctrl+C rồi chạy lại. 7. Cập nhật các mục "chưa kiểm chứng" ở đây và trong skill `telethon-engine`; ghi ngày và phiên bản đã kiểm. 8. Nếu pool hỏng mà chưa sửa được: `[limits] max_requests = 0` đưa việc truyền file về cách của Telethon (không dùng phần private nào ngoài `_file_to_media` qua `send_file`). #### Lần chạy thật đầu tiên với pool và bản sửa (2026-09-20) Người dùng chạy `clone --media video --mode reupload` trên nguồn cấm lưu (tuyên bố D3), video 19, 84 và 198 MB. Kết quả: tin 2 (18,7 MB) xuống **3,9 MB/s** (chậm: có thể do lần đầu, dựng kết nối, hoặc file ở DC khác); tin 3 (84,4 MB) xuống **29,7 MB/s**; tin 4 (198 MB) bị **`HTTP 429` ở tầng truyền** ngay đầu lúc tải, trong khi tin 3 đang được tải lên, và lần chạy **thất bại với "Lỗi kết nối tới Telegram"** (`Transient`): pool thử lại 5 lần trong khoảng 15 giây rồi bỏ cuộc. Nguyên nhân có khả năng nhất (không chắc): tải xuống và tải lên cùng đi trên **kết nối chính** (spike chỉ dùng kết nối riêng) cộng ngân sách đã tăng lên khoảng 7–8 request đang bay. Đã sửa: (1) **HTTP 429 không thử lại tại chỗ** mà thành `FloodWait(60, transport=True)` cho `FloodGuard` ghi (`flood_log.kind = 'transport_429'`, số liệu để chỉnh sau), chờ và lặp lại, tối đa 5 lần rồi lần chạy nghỉ `waiting_flood` như mọi flood; (2) **tải xuống và tải lên có kết nối riêng**, không đi chung kết nối chính với các lời gọi đọc và đăng; (3) **tải xuống nhặt lại các part đã có** sau flood hay mất kết nối thay vì làm lại file 200 MB; (4) mặc định `max_requests` 8 → **4**, ngân sách bắt đầu ở 2. Test: `test_pool.py`, `test_telethon_pool.py`, `test_runner_split.py` (mọi đường trên). Còn mở: vì sao tin 2 chậm; 429 có tái diễn ở ngân sách 4 với kết nối riêng không (bạn chạy lại, xem `flood_log` bằng `tgmirror history ` hay trực tiếp); thời gian nghỉ 60 giây là ước đoán, chưa có số đo. #### Lần chạy thật thứ hai (2026-09-21): video 1,5 GB và 1,9 GB Sau bản sửa 429 (mặc định `max_requests = 4`, kết nối riêng, nhặt lại part): **không còn 429 và không lỗi**. `clone --hashtag ... --mode reupload` trên nguồn cấm lưu (tuyên bố D3): tin 15097 (1,5 GB) **tải xuống ổn định 25–30 MB/s** suốt 1,5 GB (đúng số spike với 4 request đang bay). **Tải lên chỉ 1–7 MB/s, phần lớn 2–5 MB/s** (khoảng 11 MB/s ở 52 MB đầu rồi tụt), thấp hơn nhiều so với spike (15–25 MB/s, nhưng spike chỉ đẩy 64 MB); cả 1,5 GB lên mất vài phút và là nút cổ chai của cả chu trình. Đăng thành công, lần chạy ghi 2 tin đã sao chép; người dùng dừng ở tin thứ hai (`q`), chạy tiếp bằng `tgmirror run 13`. Chưa biết video có hiện đúng là video không (người dùng chưa báo). Nguyên nhân tải lên chậm **chưa rõ**, ba giả thuyết: (a) **Telegram hạn tốc độ tải lên bền vững** (mẫu "nhanh lúc đầu rồi tụt" khớp; spike 64 MB không thấy); (b) ngân sách request của ta bị giảm âm thầm bởi các lần phản kháng không phải flood (kết nối đóng, quá 30 giây không trả lời) và chỉ tăng lại một bậc mỗi 32 part sau 30 giây yên tĩnh, nên kẹt gần 1 request (3 MB/s là tốc độ của một request một lúc); (c) hai kết nối riêng cùng DC chậm hơn số đo spike. Cách phân biệt: (1) bản này **in cảnh báo khi ngân sách giảm** (`[cảnh báo] transfer requests in flight: 4 -> 2 (...)`, kèm lý do): thấy dòng đó thì là (b), không thấy thì là (a) hoặc (c); (2) `scripts/spike_throughput.py upload --mb 512 --inflight 4 --connections 2 --repeat 1 --timeline 10` (đẩy dữ liệu rác, không qua tgmirror) in tốc độ theo từng cửa sổ 10 giây: nếu cũng tụt sau vài chục MB thì là Telegram hạn tốc độ và không sửa được từ phía ta. Ghi nhận thêm: (i) `tmp_budget_mb = 2048` nên tin 1,9 GB **không được tải trước** trong lúc tin 1,5 GB đang tải lên (tổng > 2 GB): chu trình thành tuần tự, tải xuống + tải lên; tăng `tmp_budget_mb` (đĩa cho phép) nếu muốn chồng lên nhau; (ii) hachoir in `[warn] [] ...` khi Telethon thử đọc thông tin file lớn: chỉ là tiếng ồn, đã tắt (`hachoir.core.config.quiet`); (iii) Telethon in `Server response had invalid buffer` cho lỗi tầng truyền, ta đã xử lý nhưng dòng của Telethon vẫn hiện. **Lần chạy thứ ba (2026-09-21, lần chạy 15)**: một **album 2 video** (1,2 GB mỗi cái, 2,4 GB) từ nguồn cấm lưu. Tải xuống lại ổn định **28–32 MB/s** cho cả hai file (tuần tự, mỗi file qua pool). **Tải lên album mất khoảng 24 phút, trung bình ~1,7–2,5 MB/s** (dao động 0,8–4,4 MB/s), không có cảnh báo nào của pool. Lý do đơn giản: **album không đi qua pool khi tải lên** (chỉ tin đơn là tài liệu/video ≥ 10 MB mới đẩy trước bằng pool): nó là `send_file([...])` của Telethon, tuần tự từng file, một request một lúc, đúng cách cũ. Số này gần bằng lần chạy 13 (tin đơn 1,5 GB **có** pool: ~3,2 MB/s trung bình) nên **pool tải lên không cho được số spike (15–25 MB/s) trong lần chạy thật**; cùng dạng "khởi đầu nhanh rồi tụt" (giả thuyết Telegram hạn tốc độ tải lên bền vững vẫn mạnh nhất). Chưa có cảnh báo pool nào để loại giả thuyết ngân sách tụt (lần chạy 13 chạy trước khi có cảnh báo; lần 15 không dùng pool tải lên). **Chưa nên** làm đường album tải lên bằng pool (dựng `InputMediaUploadedDocument` + `UploadMediaRequest` + `SendMultiMediaRequest` thủ công, vì Telethon không cho truyền thuộc tính từng tin khi gửi album từ handle) cho tới khi có số `--timeline`: nếu Telegram hạn tốc độ tải lên thì công sức đó chỉ được ~2 lần; nếu không thì là ưu tiên số một. Cách kiểm nhanh hơn cả: thử **gửi bằng mã file** với nguồn cấm lưu (`scripts/spike_reference.py ... --yes-i-administer-this-channel`, lời tuyên bố D3 của người dùng): nếu Telegram chấp nhận thì việc tải lên biến mất hoàn toàn cho cả album. Hiển thị: dòng tiến độ tải lên dài (350 dòng cho 2,4 GB) đã được giảm (chỉ in khi tiến thêm 5% hoặc sau 30 giây; chưa xong thì không bao giờ hiện 100%). Đã làm: cảnh báo khi ngân sách giảm (logger `tgmirror.core.pool`, CLI in `[cảnh báo] ...` ra stderr, bền với console không có tiếng Việt), tắt hachoir ồn, `--timeline` cho spike tải lên. **Kết quả hai spike (2026-09-21, người dùng chạy).** 1. **Gửi album bằng mã file từ nguồn cấm lưu: Telegram từ chối.** `spike_reference.py ... 209041 209039 --album --yes-this-is-a-test-channel --yes-i-administer-this-channel` (hai video 321 MB và 175 MB, nguồn `noforwards=True`): `ChatForwardsRestrictedError: You can't forward messages from a protected chat`, từ `SendMultiMediaRequest`. Không sửa mã: `router(..., by_reference=not run.options.src_protected)` đã không bao giờ chọn `Strategy.REFERENCE` cho nguồn đó, và câu trả lời khép lại "cách kiểm nhanh hơn cả" ở trên: với nguồn cấm lưu, tải lên album là **không thể tránh**, nên tốc độ tải lên quyết định thời gian chạy. Chưa thử tin đơn (`SendMediaRequest`; chạy không có `--album`), nhiều khả năng cùng kết quả. 2. **`spike_throughput.py upload --mb 384 --inflight 8 --connections 1,2,4 --repeat 1 --timeline 10`** (dữ liệu rác, big file 768 part; một lượt mỗi cấu hình): | Kết nối | Kết quả | MB/s theo cửa sổ 10 giây | |---|---|---| | 1 | quá 90 s chưa xong (~283 MB đã đi, ~3,1 MB/s) | 7,7 2,4 3,4 1,9 2,7 2,9 3,0 2,5 1,8 | | 2 | 18,2 MB/s, xong sau ~21 s | 22,9 15,3 0,1 | | 4 | 27,6 MB/s, xong sau ~14 s | 29,1 9,3 | Đọc số: (i) **Không thấy Telegram hạn tốc độ tải lên bền vững** ở 2 và 4 kết nối: cả 384 MB (gấp 6 lần lượt spike trước) chạy hết ở 18–28 MB/s, cửa sổ đầu không hơn hẳn cửa sổ sau. Chỉ so trong ≤ 21 s: chưa loại được việc tụt sau vài phút hay vài GB (lần chạy thật 1,5 GB kéo dài vài phút). (ii) **Một kết nối là chỗ nghẽn**: 8 request trên 1 kết nối chỉ nhanh ở 10 giây đầu (7,7) rồi ~2–3 MB/s suốt 80 giây, bằng tốc độ một request một lúc (3,5 MB/s) và đúng dạng "nhanh lúc đầu rồi tụt" của các lần chạy thật. Lượt 1 kết nối chạy đầu tiên (có thể còn "lạnh") và mỗi cấu hình chỉ một lượt, nên đây là dấu hiệu chứ chưa phải kết luận (`--repeat 3`; lượt 64 MB trước đó cho 1 kết nối × 8 request 18,9, nhiễu 5,3–19,1). (iii) Số thật (~3 MB/s với pool, `upload_connections = 2`, ngân sách ≤ 4) thấp hơn nhiều so với 2 kết nối của spike (18 MB/s; 14,7 ở 4 request/64 MB), nên ngân sách 4 không đủ giải thích. **Giả thuyết còn lại (d), chưa kiểm**: kết nối tải lên thứ hai (hoặc cả hai) **không tạo được và pool âm thầm rơi về một kết nối, hay về kết nối chính**. Đọc mã: `_upload_senders` (`core/telethon_gateway.py`) nuốt lỗi của `_new_sender` (`except Exception: break`) và dùng kết nối chính nếu không tạo được cái nào, không in gì; ~3 MB/s trùng với tốc độ một kết nối. Spike tải xuống đã thấy server đóng kết nối ở một số cấu hình nhiều kết nối. Cách kiểm rẻ nhất: in cảnh báo (cùng đường `[cảnh báo]`) khi số kết nối tải lên tạo được ít hơn `upload_connections`, rồi chạy lại một video lớn. **Đã làm (2026-09-21)**: `_upload_senders` và `_download_sender` (logger `tgmirror.core.telethon_gateway`) nói ra, một lần cho mỗi gateway vì kết nối được giữ: `[cảnh báo] upload connections: only 1 of 2 could be made (ConnectionError: ...); uploads are slower than they should be` (hay "uploads share the main connection, which is much slower" khi không tạo được cái nào), và `download connection could not be made (...)`. Test ở `test_telethon_pool.py` (lỗi, một phần, không lỗi thì im lặng), hai đột biến mới trong `scripts/mutation_check.py` (đã chạy: **52/52 bắt được** sau khi sửa mẫu "FloodWait bị nuốt" của pool, mẫu đó không còn khớp mã sau bản sửa 429 nên lần chạy trước chỉ được 51/52). **Việc còn lại cho bạn**: chạy lại một **video đơn** ≥ 10 MB (không phải album: album không qua pool, xem lần chạy 17 dưới đây) bằng `--mode reupload`; thấy dòng đó thì (d) đúng và nguyên nhân là lỗi tạo kết nối (chữ trong ngoặc cho biết lỗi gì), không thấy thì (d) bị loại và nghi ngờ còn lại là Telegram hạn tốc độ sau vài phút. **Lần chạy thật thứ tư (2026-09-21, lần chạy 17, sau khi có cảnh báo kết nối).** `clone --hashtag '#SC' --mode reupload` từ nguồn cấm lưu (tuyên bố D3), đích forum. Tải xuống ổn định 16 → 26–29 MB/s (892 MB, rồi 277 MB ở 28,9 MB/s). **Không có cảnh báo nào** (pool hay kết nối), nhưng lần chạy này **không kiểm được (d)**: unit đầu là một **album** (dòng "Tải lên tin 188826" cộng 892,6 MB, hơn 892,4 MB của file 188827 đang tải xuống một chút: một tin nhỏ cộng video, tiến độ báo theo tin đầu của album; không có dòng tải xuống nào cho 188826 vì nhỏ hơn 8 MB), nên tải lên đi qua `send_file([...])` của Telethon trên **kết nối chính**, một request một lúc, và `_upload_senders` không được gọi. Tốc độ: **2,0 MB/s** ở 45–61 %, rồi **0,7–1,0 MB/s** (có lúc 215 KB/s) từ 65 % trở đi, khi không còn gì khác đang tải, tức tụt dần và tệ hơn cả 3,5 MB/s của "một request một lúc" ở spike. Suy ra từ tiến độ, không phải kết luận (dán lại chưa chắc đủ dòng). Hệ quả cho hàng việc: **đường album qua pool (việc 5) trở nên đáng làm** vì (1) và (i), nhưng làm sau khi (d) được xác nhận hay loại, kẻo dựng đường mới trên cùng một pool chậm. **Đối chứng bằng Telegram Desktop (2026-09-21, người dùng đo tay, cùng tài khoản).** Một file ~300 MB lên trong ~10 giây (~30 MB/s); một file **3,8 GB lên trong 2 phút 2 giây (~31 MB/s), ổn định gần hết thời gian**, CPU tăng ~10–15 % (chưa rõ tính trên tổng hay một lõi) và không tăng thêm khi file lớn. Đọc số: (i) **không có trần bền vững cấp tài khoản ở ~30 MB/s** (2 phút, 3,8 GB, không tụt; nhưng kết nối của ta tụt, xem "Spike 90 giây" ngay dưới, nên đây không loại được giả thuyết hạn tốc độ theo kết nối); file > 2 GB cho thấy tài khoản là Premium (chưa xác nhận). (ii) ~31 MB/s **trùng với spike** (18–28 MB/s với 2–4 kết nối), nên đó có thể là trần của tài khoản hay của đường truyền nhà (250 Mbps), không phải thứ Python không đạt được; đoạn "TDesktop pipelining / zero-copy nên nhanh hơn Telethon" từng được nêu là không có căn cứ (Telethon đã pipeline nhiều request trên một kết nối; 1 kết nối × 8 request vẫn chậm ở spike). (iii) Khoảng cách cần giải thích là **~1–3 MB/s của lần chạy thật so với ~30 MB/s**, không phải 30 so với 100. Nghi ngờ còn lại: (d) kết nối upload rơi về một kết nối; album đi `send_file` tuần tự; và tải xuống chạy cùng lúc với tải lên trong `clone` (spike đo từng chiều riêng, trừ `both`). Việc kế tiếp: xem "Spike 90 giây" ngay dưới, nó đổi thứ tự ưu tiên. **Spike 90 giây (2026-09-21, người dùng chạy).** `spike_throughput.py upload --mb 1500 --inflight 8 --connections 2,4 --timeline 30`, ba lượt mỗi cấu hình; **mọi lượt hết 90 giây (TIMEOUT) mà chưa xong 1500 MB**, nên "median 0,00" chỉ là do TIMEOUT, số thật là các cửa sổ: | Kết nối | MB/s theo cửa sổ 30 giây (ba lượt) | Trung bình 90 s (tính lại) | |---|---|---| | 2 | 10,7 7,0 3,7 · 7,5 4,2 3,5 · 9,4 4,9 2,5 | 5–7 MB/s | | 4 | 13,5 7,1 8,7 · 17,1 6,4 12,2 · 19,2 7,2 7,7 | 10–12 MB/s | Đọc số (suy luận, chưa kiểm): (a) **tốc độ tụt 2–4 lần trong 60 giây đầu ở mọi lượt**. 2 kết nối kết thúc ở 2,5–3,7 MB/s, đúng ~3 MB/s của các lần chạy thật (`upload_connections = 2`), và tái hiện được **không cần mã tgmirror**: pool không phải nguyên nhân, giả thuyết (d) hạ xuống thứ yếu. Spike 384 MB ở trên chỉ ≤ 21 giây nên chưa thấy tụt; nhận xét (i) của nó ("không thấy hạn tốc độ bền vững") không còn đứng vững. (b) Không giống ngân sách cấp tài khoản cạn dần: cửa sổ đầu **không giảm** qua các lượt liền nhau (2 kết nối 10,7 → 7,5 → 9,4; 4 kết nối 13,5 → 17,1 → 19,2). (c) Nhiều kết nối nâng "đáy": ~1,5–2 MB/s mỗi kết nối sau khi tụt (một kết nối ở spike trước: 2–3), gợi ý hạn tốc độ theo từng kết nối/phiên với một đợt burst đầu. (d) TDesktop giữ ~31 MB/s trên cùng tài khoản: hoặc nó tránh được cơ chế này (bằng cách nào: chưa biết), hoặc nguyên nhân ở phía client (Windows/asyncio; chưa đo CPU). Đã kiểm tiếp ngay sau (đoạn dưới). **Kết quả tiếp (cùng ngày, người dùng chạy).** (1) **CPU không phải chỗ nghẽn**: dao động 0–4 % với 2 kết nối, 3–7 % với 8 kết nối (đơn vị chưa rõ, nhưng thấp hơn nhiều một lõi). (2) 2 kết nối chạy lại: 5,6 3,0 2,5 · 6,6 3,6 2,8 · 14,3 6,0 5,4 MB/s theo 30 giây, vẫn hết 90 giây chưa xong; đáy vẫn 2,5–5,4, cửa sổ đầu dao động nhiều giữa các lượt. (3) **`--connections 8 --inflight 8` (một request mỗi kết nối): xong 1500 MB trong ~60 giây, không TIMEOUT, median 24,3 MB/s [23,3 24,3 26,0]**; cửa sổ 29,7 → 20,3 ở cả ba lượt (hai đuôi 2,5 và 0,6 là cửa sổ cuối chưa đầy). Không có 429. Cùng cỡ ~31 MB/s của TDesktop. Vẫn tụt (~30 %) nhưng nhẹ hơn nhiều so với 2 kết nối (3–4 lần); cửa sổ thứ hai ~2,5 MB/s mỗi kết nối, khớp mô hình "~2 MB/s mỗi kết nối sau burst". Hai biến đổi cùng lúc (số kết nối 2 → 4 → 8 và số request mỗi kết nối 4 → 2 → 1) nên chưa tách được cái nào quyết định. (4) Hệ quả: `upload_connections = 2` (trần 3) và ngân sách `max_requests` ≤ 4 rất có thể là lý do ~3 MB/s của lần chạy thật; ~24 MB/s cần tới 8 kết nối. **Chưa làm**: nâng trần nới mốc chống flood ở `05-chong-flood.md` và chưa đo khi tải xuống chạy đồng thời, nên cần người dùng duyệt. Chưa kiểm: `--recycle` (spike chưa có tùy chọn này; ít cần hơn nay); `--mb 3000 --connections 8` (xem có tụt tiếp không, TIMEOUT 90 giây cho ba cửa sổ); `--connections 4 --inflight 4` (tách hai biến). **Spike `both` với 8 kết nối tải lên (2026-09-21, người dùng chạy) — 429 khi chạy cùng lúc.** `spike_throughput.py both --up-connections 8 --up-inflight 8` (mặc định `--down-inflight 8`, 1 kết nối tải xuống, 64 MB mỗi chiều, `--repeat` mặc định 3 nhưng dừng ở lượt đầu vì lỗi): - **Riêng từng chiều**: tải xuống 27,8 MB/s, tải lên 27,2 MB/s — cả hai gần mức TDesktop (~31 MB/s), khớp "đường tải lên không nghẽn CPU, nghẽn ở số kết nối" của mục trên. - **Cùng lúc**: `Server response had invalid buffer: ... (HTTP code 429)` lặp lại, rồi tải xuống lỗi (`InvalidBufferError`) và tải lên TIMEOUT sau 90 giây. Đây là lỗi 429 **cấp transport**, đúng loại đã ghi ở `core/pool.py` (16 request trong lúc bay từng gây 429 với 3 kết nối) — ở đây là **8 tải xuống + 8 tải lên = 16 request cùng bay, trên 9 kết nối** (1 tải xuống + 8 tải lên), khớp con số cũ dù cách chia kết nối khác. - Đọc số (giả thuyết lúc đó, **bị số quét dưới đây bác bỏ một phần**): trần an toàn có vẻ tính theo tổng số request đang bay của cả tiến trình. `pool()` của spike không có AIMD/backoff (khác `RequestBudget` thật), nên đây là lỗi trần trụi không được che. - **Hệ quả cho việc nâng `upload_connections` lên 8**: không nên làm trực tiếp nếu `clone` thật vẫn tải xuống song song (nó luôn vậy). Số kết nối tải lên an toàn khi chạy cùng tải xuống chưa biết lúc đó — cần quét (`--up-connections 2,4,6` cùng `both`). **Quét `--up-connections 2,4,6` (2026-09-21/22, sau khi sửa `spike_throughput.py both` để nhận list).** Cùng một tin (64 MB mỗi chiều, `--down-inflight`/`--up-inflight` giữ nguyên 8, tức **số request đang bay không đổi giữa ba cấu hình — chỉ số kết nối tải lên đổi (2 → 4 → 6)**, kết nối được tạo mới cho mỗi cấu hình: | Kết nối tải lên | Riêng (tải xuống / tải lên) | Cùng lúc | |---|---|---| | 2 | 25,65 / 23,31 MB/s | Nhiều lỗi giao thức tự hồi phục (`invalid buffer`, `invalid checksum` — log của Telethon tự ghi "gói này nên bị bỏ qua", `wrong session ID`), **nhưng không lỗi cấp `pool()`**: cả ba lượt lặp chạy hết, tải xuống 22,18 MB/s, tải lên 16,60 MB/s (median) | | 4 | 23,12 / 23,12 MB/s | Lượt 1 xong (27,3 / 19,5 MB/s), lượt 2 gặp **429 cấp transport** cho cả hai chiều, dừng theo cơ chế bỏ sớm mới thêm | | 6 | 22,60 / 24,57 MB/s | Tải xuống vẫn xong (28,9 MB/s), **tải lên treo tới TIMEOUT 90 giây** và server chủ động đóng một kết nối ("0 bytes read on a total of 8 expected bytes") — nặng hơn 429, im lặng không trả lỗi | Đọc số: (a) **Giả thuyết "trần theo tổng request đang bay" ở trên bị bác bỏ**: số request đang bay giữ nguyên 16 (8 tải xuống + 8 tải lên) ở cả ba cấu hình, nhưng chỉ 2 kết nối tải lên chạy được, 4 kết nối đã 429, 6 kết nối treo hẳn. Vậy chỗ vỡ nằm ở **số kết nối mở đồng thời khi có tải xuống chạy cùng**, không phải số request đang bay. (b) Đối chiếu với mục "8 kết nối, 24 MB/s" ở trên: đó là tải lên **một mình**, hoàn toàn sạch. Ở đây "riêng" (`alone`) của cả ba cấu hình 2/4/6 cũng sạch (22–25 MB/s). Chỉ **"cùng lúc"** (tải xuống chạy song song) mới vỡ, và vỡ ngay từ 4 kết nối tải lên — thấp hơn nhiều so với 8 kết nối chạy một mình. (c) Không tách được vì sao: có thể do mở nhiều kết nối gần như đồng thời (tải xuống và tải lên đều tự kết nối trước khi vào vòng lặp, `asyncio.gather` khiến việc mở kết nối của cả hai chồng lên nhau), có thể do cùng lúc có nhiều kết nối đi cùng DC — chưa đọc đủ mã Telethon để nói chắc. - **Hệ quả cho cấu hình**: **`upload_connections = 2` (giá trị hiện tại) là mức an toàn nhất đã đo được khi tải xuống chạy cùng lúc** — đúng bằng mặc định đang có, không phải mức cần nâng lên. Không nâng lên 4 hay 6: 6 kết nối gây treo và server chủ động đóng kết nối, tệ hơn một 429 bình thường. Việc "nâng trần lên 8" **coi như xong, kết quả là giữ nguyên 2** — bỏ mục "chưa làm: nâng trần" ở trên. - **Khoảng cách chưa giải thích**: kể cả ở kết nối=2, "cùng lúc" trong spike vẫn ra 16,6 MB/s tải lên, còn lần chạy thật (13) với đúng `upload_connections = 2` chỉ ra ~3,2 MB/s. Nghi ngờ giờ chuyển sang: (1) `max_requests` (ngân sách `RequestBudget` dùng chung, mặc định thấp hơn nhiều 16) siết tốc độ thật thấp hơn mức trần kết nối cho phép — cần đo `RequestBudget` thật lúc chạy, không phải `pool()` trần trụi của spike; (2) lần chạy 13 dài vài phút, spike `both` chỉ vài chục giây — chưa loại khả năng tụt thêm theo thời gian ở mức 2 kết nối. Giả thuyết (d) (kết nối thứ hai không tạo được) đã bị hạ xuống thứ yếu trước đó vẫn đứng, vì đây là bằng chứng thứ hai cho thấy 2 kết nối tự nó không phải nguyên nhân của ~3 MB/s. - **Việc kế tiếp**: đo `max_requests` thật (không phải spike) trong một `clone --mode reupload` một video đơn ≥ 10 MB, xem ngân sách có tụt xuống dưới mức lẽ ra 2 kết nối cho phép không. Đường album qua pool (việc 5) **giữ nguyên đáng làm** vì `upload_connections = 2` không cần đổi để làm nó — nhưng kỳ vọng tốc độ nên hạ xuống quanh 16 MB/s (kết nối=2, cùng lúc, spike), không phải 24 MB/s (kết nối=8, một mình). **Đề xuất đổi chiến thuật: bỏ tải-trước, tải rồi gửi lần lượt (2026-09-22, người dùng đề xuất, sau khi thấy 429/treo ở mục trên).** Đây **không phải mã mới**: `[limits] prefetch = 0` đã làm đúng việc này, đã cài đặt và có test riêng (`test_without_prefetch_each_unit_is_downloaded_after_the_previous_one_is_sent`, `tests/integration/test_runner_reupload.py`). Cơ chế (đọc mã, `engine/reupload.py::Window`/`Pipeline`, `engine/runner.py::_ready`/`_process`): `Window(prefetch + 1, tmp_budget_mb)`; `window.release` chỉ chạy trong `Runner._process`'s `finally` sau khi unit hiện tại **gửi xong** (`pipeline.finish`), không phải sau khi tải xong. Với `prefetch = 0` sức chứa cửa sổ là 1 unit: unit kế không `reserve` được (nên không tải) cho tới khi unit hiện tại được giải phóng, tức đã gửi xong — **tải và gửi không còn chồng lên nhau bằng mã có sẵn, chỉ cần đổi cấu hình.** `upload_connections`/`max_requests` (nhiều kết nối *trong một file*, `core/pool.py`) là trục khác, không đổi bởi `prefetch`; `--connections 8` chạy một mình ở mục trên vẫn giữ nguyên tốc độ dù `prefetch = 0`. - **Vì sao đáng thử**: mục quét `--up-connections` ở trên đo đúng cảnh "tải xuống unit kế + tải lên unit hiện tại cùng lúc" (kịch bản của `prefetch = 1`, mặc định) và thấy nó vỡ từ 4 kết nối tải lên trở lên, mặc định 2 kết nối vẫn còn lỗi giao thức tự hồi phục dù chưa vỡ hẳn. `prefetch = 0` loại bỏ hẳn cảnh đó. - **Cái mất**: tải là nửa nhanh (25–30 MB/s), tải lên là nửa chậm (~3–16 MB/s ở lần chạy thật); tải-trước vốn chỉ giấu được nửa nhanh dưới nửa chậm, lợi ích tối đa khoảng 10–15% thời lượng mỗi unit (thời gian tải, nếu unit kế đã tải xong trong lúc unit này gửi). Với chênh lệch tốc độ hiện tại, mất lợi ích đó có thể rẻ hơn rủi ro 429/treo. - **Chưa biết**: tốc độ tải lên thật (~3 MB/s) có giảm thêm nữa không khi không còn tải chạy nền cùng lúc — nếu ~3 MB/s vốn do `max_requests` (ngân sách chung) chứ không phải do tranh chấp kết nối với tải xuống, thì `prefetch = 0` không đổi được số đó, chỉ đổi được sự ổn định (không còn nguy cơ 429/treo). - **Việc cho người dùng**: đặt `prefetch = 0` trong `config.toml` (`%APPDATA%\tgmirror\config\config.toml` trên Windows qua `platformdirs`; wizard/`clone` không có cờ CLI riêng cho `prefetch`, chỉ đọc từ file — xem `docs/02-cli-ux.md` khối `[limits]`), chạy lại **cùng video đơn ≥ 10 MB** bằng `--mode reupload` như mục "việc kế tiếp" ở trên, so tốc độ và có 429 không với lần chạy `prefetch = 1` (mặc định) cũ. Kết quả quyết định có nên đổi **mặc định** `prefetch` (hiện là 1, `core/config.py`) hay chỉ để người dùng tự chỉnh tùy máy/mạng. **Chiến thuật khác, đang thử (2026-09-22, người dùng đề xuất): vẫn dùng pool, nhưng không trộn hai chiều — tải xuống vài file, rồi tải lên vài file, rồi lặp lại; đĩa (`tmp`) chặn RAM như cơ chế `Window` đã có.** Đây gần với "Kế hoạch tăng tốc" đã chốt hướng nhưng chưa làm (mục dưới): một ngân sách request dùng chung, nhiều file cùng chiều chạy đồng thời dưới ngân sách đó, không bao giờ hai chiều cùng lúc — khác `prefetch ≥ 1` (đang trộn hai chiều, spike ở trên đã thấy vỡ) và khác cả `--connections 8` chạy một file một mình (không kiểm được nhiều file chung ngân sách). - **Đã sửa `spike_throughput.py` để đo trực tiếp**: lệnh con mới `files download|upload` — `--files` (bao nhiêu file chạy cùng lúc, mỗi file có `--connections` kết nối riêng, một request mỗi kết nối) × `--max-requests` (ngân sách **dùng chung** giữa mọi file đang chạy, một `asyncio.Semaphore`, không có AIMD — gần giống `core/pool.py::RequestBudget` nhưng cố định, không tăng/giảm). `download` cần một danh sách id tin, một cho mỗi file (`--files` chọn N id đầu); `upload` tự bịa file như lệnh `upload` cũ. Không trộn `download`/`upload` trong cùng lệnh (dùng `both` cho việc đó). - **Đã chạy (2026-09-22, người dùng, cùng một kênh thật, `--files 2,4,8 --max-requests 4,8,16`, 64 MB/file, 2 kết nối/file).** Hai chiều phản ứng **ngược hẳn nhau**: | files \ budget | tải xuống | tải lên | |---|---|---| | 2 | 4: 24,9 sạch · 8: 27,0 sạch · 16: vỡ (lượt 1 ổn 27,9, lượt 2 TIMEOUT) | 4: 17,8 sạch · 8: 15,6 sạch · 16: 17,9 sạch | | 4 | 4: 24,7 sạch · 8: **vỡ ngay** (429 + TIMEOUT) · 16: vỡ ngay (TIMEOUT) | 4: 17,9 sạch · 8: 23,6 sạch · 16: **33,3 sạch** | | 8 | 4: vỡ · 8: vỡ · 16: vỡ (người dùng dừng bằng Ctrl+C) | 4: 17,8 sạch · 8: **32,8 sạch** · 16: vỡ (TIMEOUT ngay lượt 1) | Đọc số: (a) **Tải xuống không chịu được nhiều file cùng chiều**: an toàn chỉ ở 2 file (24,9–27,0 MB/s, không hơn một file chạy một mình — tải xuống vốn đã gần no băng thông nên không có gì để lời); từ 4 file trở lên vỡ ngay cả ở `max-requests` thấp nhất (4). Đúng dạng lỗi cũ ("Server closed the connection: 0 bytes read on a total of 8 expected bytes") lặp dày đặc — **lần này không có tải lên nào chạy cùng**, nên giả thuyết "chỉ vỡ khi trộn hai chiều" (mục `prefetch`/`both` ở trên) **bị bác bỏ một phần**: một chiều thôi, nhiều file, cũng đủ vỡ. (b) **Tải lên chịu được tốt hơn hẳn**: sạch tới tận 8 file/budget 8 (**32,8 MB/s tổng — cao nhất từ trước đến giờ trong mọi spike**, gồm cả "8 kết nối một file, một mình" 24,3 MB/s), chỉ vỡ ở 8 file/budget 16. 4 file/budget 16 cũng sạch, 33,3 MB/s. (c) Không tách được vì sao hai chiều khác nhau: nghi ngờ (chưa đọc đủ mã Telethon để chắc) — tải xuống của nguồn không cùng DC với tài khoản dùng `_create_exported_sender` (đường ủy quyền chéo DC), tải lên luôn tới DC nhà bằng sender thường; mở nhiều `_create_exported_sender` cùng lúc tới cùng một DC ngoài có thể bị soi khác với sender thường. Chưa kiểm DC của các tin dùng để test có khác DC nhà không (`download` in ra dòng đó). - **Hệ quả**: bỏ hẳn "nhiều file cùng lúc" cho **tải xuống** — không đáng, lợi ích gần như không có (tải xuống đã nhanh sẵn) mà rủi ro vỡ cao. **Giữ lại cho tải lên**: đây là nửa chậm, đang là chỗ nghẽn thật (~3 MB/s lần chạy thật), và 8 file/budget 8 vừa cho số cao nhất đã đo được. Vậy hình dạng đáng làm không phải "down vài file, up vài file, đối xứng", mà là: **tải xuống từng file một (hoặc tối đa 2), tích đủ một lô trên đĩa, rồi tải lên cả lô cùng lúc (nhiều file, chung ngân sách)** — bất đối xứng có chủ đích, không phải chỉ vì thận trọng. - **Cảnh báo (đọc lại `telethon-engine` skill, 2026-09-22): con số 32,8 MB/s chưa cùng hình dạng với mã sản xuất, chưa nên tin thẳng.** `core/telethon_gateway.py::_upload_senders` giữ và **tái dùng** một bộ `upload_connections` (mặc định 2) kết nối cho lần tải lên kế tiếp ("made once and kept for the next file"). Spike `files upload` thì mở **kết nối mới cho từng file, từng lượt lặp** — 8 file × 2 kết nối riêng = 16 kết nối cùng tồn tại, khác hẳn "8 file chia nhau 2 kết nối có sẵn" mà sản xuất sẽ làm. Không biết hình dạng thật (ít kết nối, tái dùng, nhiều file xen part) có đạt được 32,8 MB/s hay vỡ sớm hơn vì mỗi kết nối phải gánh nhiều file hơn. - **Việc kế tiếp, theo thứ tự**: (1) **sửa spike để giống hình dạng sản xuất**: mở đúng `--connections` kết nối một lần, dùng chung (tái sử dụng, xen part) cho mọi file trong `--files`, thay vì mỗi file tự mở kết nối riêng — đo lại `--files × --max-requests` với hình dạng đó trước khi tin số cũ; (2) kiểm DC của tin test so với DC nhà, để biết chỗ vỡ tải xuống có phải do exported sender không; (3) nếu số đứng vững với hình dạng đúng, đây là cơ sở để dựng lại `Window`/`Pipeline` (hoặc bộ lập lịch "Kế hoạch tăng tốc" dưới) theo hướng bất đối xứng trên, thay vì `prefetch=0` tuần tự nghiêm ngặt (mục trên) hay `prefetch≥1` hiện tại (trộn hai chiều). Ba hướng nên so cùng một video/bộ file thật trước khi chọn. **Chạy lại với hình dạng đúng (2026-09-22, người dùng, `spike_throughput.py` sửa: `--connections` kết nối mở **một lần, dùng chung**, xen part giữa mọi file thay vì mỗi file tự mở kết nối riêng — đúng cách `_upload_senders`/`_download_sender` thật hoạt động). Kết quả **đảo ngược khuyến nghị ở trên**: hình dạng đúng vỡ **sớm hơn và nặng hơn** hình dạng sai (nhiều kết nối riêng), ở cả hai chiều. | files \ budget | tải xuống (2 kết nối chung) | tải lên (2 kết nối chung) | |---|---|---| | 2 | 4: 29,6 sạch · 8: **vỡ ngay** (429) · 16: vỡ (lượt 1 ổn 5,4–5,7 rồi vỡ) | 4: 14,0 sạch · 8: 21,0 sạch · 16: 14,4 sạch (nhiễu 10,3–37,0) | | 4 | 4: **vỡ** (TIMEOUT) · 8: vỡ (429) · 16: vỡ (429) | 4: 10,2 sạch · 8: 18,5 sạch (nhiễu, tự hồi) · 16: **24,9 sạch** (nhiễu 12,8–37,0) | | 8 | 4: vỡ (TIMEOUT) · 8: vỡ (429) · 16: vỡ (429) | 4: **vỡ** (TIMEOUT) · 8: vỡ (TIMEOUT) · 16: vỡ (TIMEOUT) | Đọc số: (a) **Tải xuống**: chỉ còn đúng một ô sống — 2 file/budget 4 (29,6 MB/s, không hơn một file một mình). Mọi ô khác vỡ, kể cả 4 file/budget 4 (trước đây với kết nối riêng thì sạch 24,7 MB/s) — **tệ hơn hẳn** bản kết nối riêng. (b) **Tải lên**: sống tới 4 file (24,9 MB/s ở budget 16, dù nhiễu), nhưng **8 file luôn TIMEOUT ở cả ba mức ngân sách** — khác hẳn kết quả cũ (8 file/budget 8 từng sạch 32,8 MB/s). (c) **Kết luận ngược với lần trước**: con số 32,8 MB/s (và các ô "sạch" ở 8 file trong bảng cũ) là **hiện tượng của hình dạng sai** — mở nhiều kết nối *mới, riêng cho từng file* né được chỗ nghẽn mà 2 kết nối *dùng chung, tái sử dụng* của sản xuất gặp phải. Với đúng số kết nối sản xuất sẽ mở (2), việc dồn nhiều file qua cùng một bộ kết nối nhỏ **không có lời, và dễ vỡ hơn cả chạy tuần tự** — cả hai chiều đều thấy tín hiệu này, tải xuống rõ nhất. - **Hệ quả: bỏ hẳn hướng "nhiều file qua pool" (đối xứng lẫn bất đối xứng ở trên).** Không có bằng chứng nó nhanh hơn một file chạy một mình khi dùng đúng số kết nối sản xuất; rủi ro vỡ giữa chừng (429/TIMEOUT) tăng theo số file, không giảm. Đề xuất của người dùng ("làm lần lượt", mục `prefetch=0` ở trên) vẫn là hướng an toàn nhất đã có sẵn trong mã. - **Hướng còn lại, đáng thử hơn nhiều file cùng lúc**: kết hợp `prefetch = 0` (không còn tải xuống chạy cùng lúc với tải lên — mục trên) **với nâng `upload_connections`** cho **một file tại một thời điểm**. Lý do: "8 kết nối, 8 request, một file một mình" đã đo sạch 24,3 MB/s (mục trên, trước khi có `files`); các lần `upload_connections` cao (4, 6) chỉ vỡ khi có **tải xuống chạy cùng lúc** (`both`, mục trên) — điều `prefetch = 0` loại bỏ hoàn toàn. Chưa đo `upload_connections` > 2 với `prefetch = 0` bằng lần chạy thật; đáng làm trước khi quay lại ý tưởng nhiều-file. Việc cho người dùng: `spike_throughput.py upload --mb 384 --connections 4,8,16 --inflight 4,8,16` (một file, không tải xuống nào chạy cùng — đã có sẵn, không cần sửa spike) để tìm trần kết nối/ngân sách khi chắc chắn không bị tải xuống tranh chấp, sau đó đặt `upload_connections`/`max_requests` tương ứng và `prefetch = 0`, thử một `clone --mode reupload` video đơn ≥ 10 MB. **Đã chạy (2026-09-23, người dùng), một file, không có tải xuống nào cùng lúc.** Sáu cấu hình hợp lệ (`inflight ≥ connections`): | connections \ inflight | 4 | 8 | 16 | |---|---|---|---| | 4 | 9,7 sạch | 12,6 sạch | 19,9 sạch (nhiễu 14,0–28,3) | | 8 | — | **27,75 sạch** | **vỡ** (429 + TIMEOUT) | | 16 | — | — | **vỡ** (TIMEOUT, không 429) | Đọc số: (a) **8 kết nối/8 request (1 request mỗi kết nối) lại sạch, 27,75 MB/s — lần thứ hai đo được con số này** (lần trước 24,3), củng cố đây là điểm an toàn thật, không phải may rủi. (b) **Hễ vượt "1 request mỗi kết nối" là vỡ**: 8 kết nối/16 request (2 request mỗi kết nối) vỡ vì 429; 16 kết nối/16 request (vẫn 1 request mỗi kết nối, nhưng tổng kết nối cao hơn) cũng vỡ, lần này không 429 mà TIMEOUT thẳng — không rõ do quá nhiều kết nối hay do phiên làm việc hôm nay đã mở rất nhiều kết nối dồn lại (mọi spike trong ngày cộng lại chắc chắn hơn một trăm kết nối), chưa tách được hai giả thuyết. (c) 4 kết nối luôn sạch ở mọi mức nhưng chậm hơn 8 kết nối rõ rệt (9,7–19,9 so với 27,75) — không đáng dùng. - **Kết luận: `upload_connections = 8`, `max_requests = 8` (1 request mỗi kết nối) là cấu hình tốt nhất đã đo được, tái lập hai lần.** Đừng vượt quá — cả hai cách vượt (nhiều request hơn kết nối, hay nhiều kết nối hơn 8) đều vỡ trong phiên hôm nay. **Chốt (2026-09-23, người dùng): dừng dò thêm, chọn 8/8 vì ổn định (tái lập hai lần, không cần trần cao hơn).** Làm rõ phạm vi "an toàn khi reupload nhiều file": nghĩa là **nhiều unit nối tiếp nhau trong một lần `clone`** (mỗi unit một lần tải-rồi-gửi, `prefetch=0` nên tuần tự), **không phải nhiều file cùng lúc** (hướng đó đã bị loại ở mục "chạy lại với hình dạng đúng" trên). Lý do tin nó an toàn cho một lần `clone` dài: `core/telethon_gateway.py::_upload_senders` mở 8 kết nối **một lần cho cả lần chạy** và giữ lại cho mọi unit kế tiếp ("made once and kept for the next file") — khác hẳn cách spike đo (mở kết nối mới mỗi lượt lặp/mỗi cấu hình), nên nỗi lo "kết nối tích lũy cả phiên" ở bảng trên **không áp dụng** cho một lần `clone` thật: nó chỉ mở 8 kết nối đúng một lần rồi tái dùng, không phải mở lại hàng chục lần như spike hôm nay đã làm. **Việc chuẩn bị cho session sau — đã làm (2026-09-23):** 1. `src/tgmirror/core/config.py` — đổi mặc định `Limits`: `prefetch: 1 → 0`, `upload_connections: 2 → 8`, `max_requests: 4 → 8`. `upload_connections` có trần `le=3` (chặn mặc định 8 mới): nâng lên `le=16` (khớp trần đã có của `max_requests`, vì spike đo 16 vỡ nhưng đó là trần validate, không phải khuyến nghị — comment trong code nói rõ đừng vượt 8). `prefetch` giữ nguyên `le=3`, 0 nằm trong khoảng nên không cần đổi. 2. `docs/02-cli-ux.md` — khối ví dụ `[limits]` cập nhật `prefetch = 0`, `max_requests = 8`, `upload_connections = 8`. 3. `docs/05-chong-flood.md` — bảng `[limits]` (`prefetch`, `max_requests`, `upload_connections`) cập nhật số mặc định, lý do và dẫn tới mục đo ở trên. 4. `docs/01-kien-truc.md` — mục "Chi tiết chiến lược B": câu `prefetch` đổi sang mặc định 0 kèm lý do; câu "tải lên chia ra 2–3 kết nối" đổi thành tới 8 kết nối, dẫn số đo mới. 5. Skill `flood-safety` — đoạn `max_requests` viết lại: mặc định 8, giữ nguyên câu cảnh báo cũ (đoán sai trước đây) nhưng nói rõ 8/8 đã được đo lại và tái lập hai lần, không còn là đoán. 6. Skill `telethon-engine` — dòng nêu `[limits] prefetch` (default 1) đổi thành default 0 kèm lý do ngắn. 7. `tests/unit/test_telethon_pool.py:90` — để nguyên (`upload_connections=2`): fixture độc lập với `Limits()` mặc định, không vỡ, và tách biệt là chủ đích (test pool không phụ thuộc config mặc định). 8. `tests/integration/test_runner_reupload.py` — để nguyên: các test `prefetch` đều truyền giá trị tường minh qua `model_copy`, không đọc mặc định. 9. `.venv/Scripts/python.exe -m pytest` — 1321 passed, không có test nào ngầm định giá trị cũ qua `Limits()` không tham số. `ruff check`/`ruff format --check` trên `config.py` sạch. 10. `doc-sync`: các mục 1–9 ở trên là chính lần doc-sync này. #### Đẩy byte trước khi đăng — đã làm (2026-09-20) Người dùng duyệt đổi crash-safety và pace ("đổi luôn bây giờ và test cùng với pool"). Đã có: `TelegramGateway.upload_prepared` và `Prepared.uploaded` (Telethon: `_pooled_upload`, `_Item.uploaded`; `FakeGateway`), `FloodGuard.transfer`/`check_cap`/`pace(cost, credit)`, `Limiter.check_cap` và `acquire(..., credit=)`, `Runner._mono` và thứ tự mới ở `_process` (kiểm cap → đẩy byte → `pace` với credit → cổng → write-ahead → đăng → commit). Cơ chế ở `04-state-checkpoint.md`, `05-chong-flood.md`. Kiểm bằng `tests/integration/test_runner_split.py` (thứ tự và số hàng `pending` tại từng thời điểm; kill lúc đẩy byte không để lại gì; credit theo thời gian đẩy, không rút ngắn nghỉ dài; cap kiểm trước khi đẩy; FloodWait khi đẩy lặp lại đẩy, khi đăng không đẩy lại; **cùng runner + store + `TelethonGateway` thật với pool trên client giả**), cùng các ca mới ở `test_limiter.py` và `test_telethon_pool.py`. Các test cũ không đổi (đồng hồ `mono` của Rig đứng yên nên không có credit ngẫu nhiên). Các lựa chọn khi làm (không phải D1–D9): - **Credit chỉ là thời gian đẩy byte** đo quanh `upload_prepared`, không phải mọi thời gian trôi qua từ lần đăng trước; bảo thủ hơn "≥ delay kể từ lần đăng trước", và tất định trong test. - **Chỉ tin đơn là tài liệu/video ≥ 10 MB** (đường pool) đẩy trước; album, ảnh, file nhỏ, gửi bằng mã file và forward giữ thứ tự cũ. Album không tách được vì Telethon đổi media thành tham chiếu bằng một request ghi (`messages.uploadMedia`) nằm trong chính lời gọi đăng. - **Ảnh bìa** của video vẫn được Telethon đẩy trong lời gọi đăng (nhỏ). - **Không đọc lại tin theo lô** (mục thứ ba của bản đề xuất gốc): lợi ích thấp vì đọc đã chạy nền song song với gửi. **Chưa kiểm chứng trên Telegram thật**: như mục pool, và thêm: đăng bằng `InputFileBig` đã đẩy từ trước không hết hạn khi chờ pace hoặc FloodWait dài (chưa biết file đã đẩy sống bao lâu trước khi Telegram bỏ); tốc độ thực tế của vòng đẩy → chờ → đăng so với trước. #### Kế hoạch tăng tốc (đã chốt hướng, bước 1–5 đã làm) Mô hình: **một bất biến duy nhất — số request Telegram đang bay ≤ `R`** (đọc lại tin, tải một part, đẩy một part, lệnh đăng đều chiếm một slot). Bộ lập lịch làm việc ở mức part, **unit cũ nhất được ưu tiên tuyệt đối** (kể cả giữa tải xuống của unit sau và tải lên của unit trước), nên đăng vẫn đúng thứ tự (D4), đĩa được giải phóng sớm, không deadlock, và phần đuôi file này liền mạch với phần đầu file kế. `Window` vẫn chặn đĩa. `R` tự chỉnh kiểu AIMD (FloodWait thì giảm một nửa, chạy êm thì tăng), có trần cứng cấu hình được (`[limits]`, mặc định khoảng 4 rồi đo). Số request theo dung lượng: ảnh nhỏ 1 xuống + 1 lên, file 10 MB+ đủ part để dùng hết `R`. Bộ lập lịch là phần thuần (kiểm bằng `PartTransport` giả có độ trễ ảo); adapter Telethon mỏng (theo tôi nhớ: tải tối đa 1 MiB/request và không vắt qua ranh giới 1 MiB, tải lên tối đa 512 KiB/part, file ≥ 10 MB dùng API big-file có thể gửi part song song — cần kiểm lại). Nhớ: với file nhỏ, nhiều file cùng lúc **không** làm nhanh hơn vì nhịp đăng (pace) chặn; lợi chủ yếu ở file 1–50 MB và file lớn. Cập nhật sau spike 11 và 12 (2026-09-20): gửi bằng tham chiếu **chạy được** cho video và tệp, nên bước 4 dưới đây nên làm *trước* bộ lập lịch request: một lần chạy chỉ đổi caption trên nguồn không cấm lưu nội dung sẽ có tốc độ gần chiến lược A, không cần đĩa. Số đo tải lên cho `R` mặc định khoảng 8 request trên 2 kết nối. **Bước 2 giải thích (tách đẩy byte khỏi đăng tin, pace theo deadline).** Hôm nay một unit lớn đi: `pace` (ngủ 2 s) → write-ahead (ghi `pending`) → `send_prepared` (đẩy byte **rồi** đăng tin) → `commit`. Đường truyền rảnh trong 2 s ngủ, và `pending` kéo dài suốt lúc đẩy byte. Đề xuất: đẩy byte trước (không tạo tin nào, Telegram bỏ file chưa được đăng), rồi mới chờ cho đủ ≥ 2 s **kể từ lần đăng trước**, rồi write-ahead, rồi chỉ *đăng* (một lời gọi ngắn), rồi `commit`. Đẩy byte của unit N chạy ngay sau khi đăng unit N−1, nên với file đẩy lâu hơn 2 s thì khoảng chờ đã hết khi byte xong và pace không tốn gì. Ví dụ video 55 MB (đẩy 2,5 s, đăng 0,3 s): hôm nay mỗi unit ≈ 2 + 2,8 = 4,8 s; sau đổi ≈ 2,8 s (nhanh hơn ~40%); video 500 MB (đẩy 25 s) chỉ bớt 2 s trên 27 s; ảnh nhỏ (đẩy 0,3 s) vẫn bị pace chặn như cũ. Nó **không làm tăng tần suất đăng tin quá mức đã cấu hình** (vẫn ≥ `min_delay` giữa hai lần đăng, đó mới là điều Telegram giới hạn), và có ba lợi phụ: cửa sổ `pending` chỉ còn một lời gọi đăng (crash lúc đang đẩy byte không để lại gì để reconcile), FloodWait khi đăng chỉ lặp lại lệnh đăng chứ không đẩy lại cả file, và có thể đẩy byte của unit kế trong lúc chờ. Giá phải trả: đổi thứ tự write-ahead/pace ở `runner._process`/`_send` và tách `send_prepared` thành hai lời gọi của gateway (chạm đúng vùng từng lỗi "video ra tệp"; `test_telethon_pin.py` đã giữ hành vi dựng media), kiểm `daily_cap` **trước** khi đẩy byte (không thì đẩy xong mới biết hết cap và phải đẩy lại), và nó chỉ đáng với file cỡ 10–100 MB. Người dùng đã duyệt làm ngay (2026-09-20); xem "Đẩy byte trước khi đăng — đã làm". Thứ tự đề xuất, mỗi bước xin duyệt khi đổi hành vi: 1. Spike (người dùng chạy): `spike_count.py`, `spike_reference.py`, `spike_throughput.py`. 2. ~~**Tách "đẩy byte" khỏi "đăng tin"**~~ — **đã làm (2026-09-20, người dùng duyệt)**, xem "Đẩy byte trước khi đăng — đã làm"; ghi chú gốc: **Tách "đẩy byte" khỏi "đăng tin"** (`upload_file` rồi `send_file` với handle), **pace tính sau khi đẩy byte và trước lệnh đăng, theo deadline từ lần ghi trước**, `begin_batch` dời xuống ngay trước lệnh đăng; đọc lại tin theo lô ≤ 100 unit thay vì một request mỗi unit. *Đổi hành vi crash-safety và pace: cần người dùng duyệt riêng* (`04-state-checkpoint.md`, skill `checkpoint-state`, `flood-safety`). 3. ~~`RequestBudget` + bộ lập lịch part cho tải xuống, rồi tải lên (file ≥ 10 MB); trần kết nối; AIMD; giữ trần RAM~~ — **đã làm** (xem "Pool request — đã làm"). 4. ~~Gửi bằng tham chiếu file cho tin chỉ đổi caption~~ — **đã làm** (xem trên); nguồn `noforwards` đã đo 2026-09-21: Telegram từ chối (`ChatForwardsRestrictedError`), nên nguồn đó luôn tải xuống rồi tải lên; album đã được spike. 5. ~~Đường album mới (`InputMediaUploadedDocument` + `SendMultiMedia`) cho phần tải lên~~ — **đã làm (2026-09-22)**: mỗi tin của album tải lên riêng (qua pool nếu đủ lớn, ngưỡng như tin đơn), `messages.UploadMediaRequest` đổi thành media đã có id (`SendMultiMediaRequest` từ chối `InputMediaUploaded*` trần, `MediaInvalidError` — Telethon tự làm vậy trong `_send_album` của chính nó), rồi một `messages.SendMultiMediaRequest` gửi cả lô; thuộc tính/`force_file`/`nosound_video`/ảnh bìa theo từng tin, không còn `hachoir` hay một `force_document` chung cho cả album. Xem `01-kien-truc.md` "Chi tiết chiến lược B" và skill `telethon-engine`. `tests/unit/test_telethon_reupload.py`, `test_telethon_pool.py`, `test_telethon_transfer.py` cập nhật theo (mock `Stub.__call__`/`upload_file`); **chưa chạy trên Telegram thật** (xem "Còn lại của đợt tăng tốc" và skill, mục "chưa xác minh"). 6. Relay theo part (part tải xuống xong thì đẩy lên ngay, không chờ cả file) — sau khi bộ lập lịch chạy ổn. 7. Đo `flood_log` thật (spike 6) để chỉnh `min_delay`, cap ngày và delay theo dung lượng (nút cổ chai của ảnh nhỏ là pace và cap, không phải tốc độ truyền). Lưu ý cho phase 2 (đã áp dụng): schema đã có `jobs.src_kind`, `msg_map.src_topic_id`, `topic_map` (xem `04-state-checkpoint.md`) để phase 8 không cần migration. Đường code phase 1–7 vẫn viết với `kind` trong đầu, dù chỉ kiểm thử với broadcast. ### Phase 7 — ghi chú **TUI (Rich Live) — đã làm (2026-09-23).** Các phím `p`/`r`/`q` và `RunControl` đã có sẵn từ đợt "Tái thiết luồng job", nên việc còn lại đúng như `02-cli-ux.md` đã ghi: chỉ phần hiển thị. Thêm `ui/tui.py::TuiReporter`: cùng ba lời gọi `Reporter` (`notice`/`progress`/`transfer`) như `LineReporter`, vẽ đúng mock trong `02-cli-ux.md` ("Foreground TUI") bằng `rich.live.Live` (dòng đầu, thanh tiến độ, dòng đếm, dòng phím). Tiến độ/tốc độ/ETA dùng lại đúng `engine.status.estimate` (hàm thuần, không cần Store) nên `status` và TUI không bao giờ lệch số cho cùng một lần chạy. `delay` và số lần bị giới hạn không thuộc `Reporter` (đó là việc của limiter, mà `Reporter` không thấy): TUI suy ra chúng từ các `notice("throttled"/"flood_waiting", ...)` mà nó vốn đã nhận, nên `delay` hiển thị chỉ mới tới lần flood gần nhất — không biết khi delay đã giảm trở lại mà không có flood nào xảy ra kể từ đó. Chọn TUI hay `LineReporter` **không** dùng lại `Runtime.interactive`: cờ đó nghĩa là "có thể hỏi" (wizard), và bộ test wizard đặt `interactive=True` trên một `CliRunner` không phải terminal thật — nếu TUI theo cùng cờ, các test đó vô tình nhận luôn TUI và làm lệch phép so `flags.output == wizard.output` (`test_cli_clone.py`, `test_cli_run.py`; phát hiện khi chạy `pytest` sau khi nối dây lần đầu). Sửa bằng thêm `Runtime.reporter: ReporterFactory`, giống hệt cách `Runtime.keys: KeyProvider` đã tách khỏi `interactive` từ trước cho cùng lý do (hotkeys cũng chỉ có ý nghĩa khi có terminal thật): `default_runtime()` nối `terminal_reporter` khi có terminal thật, còn `make_runtime`/mọi test giữ mặc định `plain_reporter` (`LineReporter`) trừ khi tự yêu cầu khác. Windows: đã thử qua PowerShell thật (không phải Bash tool của Claude Code — thử lần đầu qua đó dựng nhầm một `UnicodeEncodeError`, hoá ra là do giả lập console của git-bash, không phải lỗi thật). Chữ có dấu hiển thị đúng, không crash. Một chỗ phải sửa: `Live` không tự xuống dòng khi thoát, nên dòng `run.result` in ngay sau sẽ dính vào dòng cuối của khung TUI trừ khi `TuiReporter.__exit__` tự in thêm một dòng trống trước. **Lỗi thật tìm thấy khi người dùng chạy `--mode reupload` thật (2026-09-23): khung TUI không hiện gì cả suốt lần chạy.** Người dùng chạy `tgmirror run` trong PowerShell thật (không phải redirect, đã xác nhận), thấy wizard chọn cặp hoạt động (nên chắc chắn có terminal thật, `interactive=True`) nhưng khung TUI không bao giờ xuất hiện — chỉ có các dòng `notice`/`transfer` chữ thường, giống hệt như không có TUI. Nguyên nhân: unit lần đó là một video 407 MB, gặp `HTTP 429` ở tầng truyền liên tục rồi `FloodWait`, nên **không có batch nào commit** trong suốt lần chạy — `TuiReporter.progress(run)` (chỗ duy nhất từng gán `self._run`) không bao giờ được gọi, nên `render()` trả về `Text("")` (rỗng) từ đầu đến cuối. Với một lần chạy nhiều unit nhỏ thì `progress()` gọi ngay sau batch đầu nên không lộ ra, nhưng một file lớn gặp flood có thể chiếm *toàn bộ* lần chạy trước khi có unit đầu tiên xong. Sửa: `TuiReporter.__init__` giờ nhận `run` (trạng thái lúc bắt đầu, `cli/commands/run.py` luôn có sẵn `current` trước khi dựng reporter) và gán thẳng vào `self._run`, cộng gọi `_refresh()` ngay trong `__enter__` — khung hiện nội dung thật (header, thanh 0%, đếm) ngay khi vào, không đợi `progress()` đầu tiên. Nhân tiện cũng cho `transfer()` gọi `_refresh()` (trước đó không gọi): một file tải lâu mà không có `notice` nào xen giữa sẽ làm khung đứng yên trông như treo, dù panel vẫn "sống". `ReporterFactory`/`plain_reporter`/`terminal_reporter` (`cli/runtime.py`) đổi chữ ký theo, nhận `Run` thay vì `src`/`dst` rời. Test hồi quy: `test_the_seed_run_is_shown_immediately_without_a_progress_call`, `test_a_transfer_refreshes_the_panel_...` (`tests/unit/test_tui.py`). Xác nhận lại bằng tay (PowerShell thật, mô phỏng đúng kịch bản: seed run rồi chỉ gọi `notice`/`transfer`, không gọi `progress()`) — khung hiện đúng ngay từ đầu. **Chưa làm**: `tgmirror doctor`, đóng gói (pipx/uv tool), tài liệu người dùng — phase 7 vẫn `[ ]` cho tới khi xong cả ba. **Đào sâu `core/pool.py` sau lần crash thật ở trên (2026-09-23, người dùng yêu cầu).** Đọc lại `run_parts`/`RequestBudget`/`_request`/`_download_sender` để tìm vì sao chuỗi `1 -> 1 (connection problem: ConnectionError)` kéo dài rồi crash với traceback thật thay vì được `FloodGuard` xử lý êm. Tìm được hai điều: 1. **`_download_sender()` không bao giờ tạo lại sender**: nó tạo một kết nối, giữ trong `self._down_sender` suốt đời gateway, và mọi lần thử lại (`run_parts`, tối đa 5 lần/part) đều dùng lại đúng sender đó — kể cả khi kết nối đã chết hẳn (không chỉ bị dội tạm thời). Nếu kết nối thật sự chết, 5 lần thử lại chỉ lặp lại đúng một lỗi cho tới khi `Transient` bỏ cuộc. **Chưa sửa** (cần quyết định: tạo lại sender sau bao nhiêu `TransportPressure` liên tiếp không phải flood, hay để Telethon tự lo — chưa rõ `MTProtoSender` có tự kết nối lại không, cần đọc thêm trước khi đổi). 2. **"Future exception was never retrieved"**: traceback không thuộc về task nào của `run_parts` (`asyncio.gather(..., return_exceptions=True)` ở `finally` đã lấy hết kết quả của các task đó) — nó là một `Future` **nội bộ của Telethon** (`_call` trong `users.py` chờ nó, `_recv_loop` sẽ set kết quả khi có phản hồi thật). Nghi vấn: `_request()` bọc lời gọi bằng `asyncio.wait_for(..., request_timeout)`; khi hết giờ, `wait_for` hủy task đang chờ nhưng future nội bộ của Telethon (đăng ký trong sender để `_recv_loop` tìm) không nhất thiết được dọn theo — nếu phản hồi (429) tới **sau** khi đã timeout và bỏ cuộc, nó set exception lên một future không còn ai chờ, và asyncio log "never retrieved" lúc future đó bị dọn rác. Không tự tin đây là lỗi của tgmirror hay là cách Telethon luôn hoạt động khi kết nối tệ; ồn nhưng có vẻ không phải nguyên nhân chính khiến lần chạy thất bại (nguyên nhân chính là mục 1: kết nối chết hẳn, thử lại vô ích). **Chưa sửa, chỉ mới hiểu.** **Việc đã làm ngay (giảm thiểu, không phải sửa tận gốc mục 1–2 trên)**: tách `[limits] max_requests` (ngân sách dùng chung) thành `download_requests` (mặc định **4**, hạ từ 8) và `upload_requests` (giữ **8**) — hai `RequestBudget` độc lập trong `TelethonGateway` (`_download_budget`/`_upload_budget`), không còn ảnh hưởng lẫn nhau. Người dùng yêu cầu sau khi thấy tải xuống ở 8 vỡ nặng (429 liên tục rồi mất kết nối) trong khi tải lên ở 8 vẫn ổn cùng lần chạy — bằng chứng hai chiều cần trần khác nhau, không phải bằng chứng hạ cả hai. Đổi: `core/config.py` (`Limits`), `core/telethon_gateway.py` (`TransferSettings`, `TelethonGateway.__init__`, `_pooled`/`_pooled_upload`/`_download_parallel`/`_upload_parallel`), `core/pool.py` (docstring, không đổi cơ chế `RequestBudget`/`run_parts`). `priority` của `run_parts` không còn ý nghĩa giữa hai chiều (mỗi chiều có ngân sách riêng) nhưng vẫn giữ trong mã như một khả năng chung của bộ lập lịch (dùng cho hai transfer chia sẻ *cùng* một ngân sách, nếu sau này cần) — bỏ hẳn các đối số `priority=1`/`priority=0` ở lời gọi từ `telethon_gateway.py` vì chúng không còn tác dụng ở đó. Test: `tests/unit/test_telethon_pool.py` (ngân sách tải xuống bị dội không đụng ngân sách tải lên), `tests/unit/test_config.py` (mặc định mới). Doc-sync: `05-chong-flood.md`, `02-cli-ux.md`, `01-kien-truc.md`, skill `flood-safety`, skill `telethon-engine`. #### Kế hoạch giao diện full-screen (menu) — Chặng 1 xong (2026-09-23) Người dùng muốn chuyển sang tương tác qua TUI **thay vì gõ lệnh**, dùng một vòng lặp, không chạy nền — chỉ sống trong đúng tiến trình `tgmirror` từ lúc mở tới lúc thoát (khác hẳn TUI đã làm ở trên, vốn chỉ là màn hình *tiến độ* trong lúc một lệnh đang chạy). Brainstorm ban đầu (giữ nguyên bên dưới) là một lớp menu điều hướng bằng bàn phím kiểu Norton Commander/Symantec Ghost (full-screen, khung cố định) bọc quanh các lệnh đã có. Hai điểm đã chốt qua hỏi trực tiếp người dùng (không phải D1–D9), **đã cài đúng như chốt**: 1. **Điểm vào**: gõ trơn `tgmirror` khi có terminal thật (`Runtime.interactive`) → vào thẳng app full-screen này (`ui/menu/app.py::launch`). Không có TTY, hoặc gõ kèm lệnh con cụ thể → giữ nguyên hành vi hôm nay. Cài bằng cách bỏ `no_args_is_help`, thêm `invoke_without_command=True` ở `@app.callback()`, và một nhánh trong `main()` (`cli/app.py::_bare_invocation`) — không nhân đôi việc parse cờ, `ctx.get_help()` vẫn in đúng help cũ cho nhánh không-terminal (`test_no_args_shows_help` không đổi). 2. **Ctrl+C** trong lúc một run đang chạy/tạm dừng được khởi từ app này luôn dừng run **và** thoát hẳn tiến trình — `RunScreen` (`ui/menu/run_screen.py`) trả `("quit", 130)` khi `stop_on_interrupt`'s `interrupt.hit` là `True`, dù dừng êm (một Ctrl+C) hay bị `KeyboardInterrupt` cứng ném giữa chừng (hai Ctrl+C — `self._interrupt_hit` được set trong `finally` để không bị exception nuốt mất). Người dùng được hỏi lại một điểm kiến trúc phát sinh khi dò code (không đổi hai điểm trên): `rich.live.Live` không lồng được hai phiên bản cùng lúc và `typer.echo` giữa alt-screen bị màn hình đè — chọn **vẽ thật sự bên trong khung ngoài** (đúng chữ brainstorm gốc) thay vì tạm thoát alt-screen rồi gọi lại lệnh cổ điển. Vì vậy `RunScreen` không gọi `execute()` (`cli/commands/run.py`) nguyên trạng (hàm đó tự mở `Live`/`rt.keys`/`typer.echo` riêng) mà tự lắp lại đúng cơ chế của nó: `TuiReporter` chỉ được gọi `notice/progress/transfer` rồi kéo `render()` mỗi khung hình (không bao giờ qua `__enter__`/`__exit__` riêng — xác nhận `render()` đã tách sẵn khỏi `Live` từ trước), `stop_on_interrupt` tái dùng y nguyên (dựa `signal.SIGINT`, không đụng việc đọc phím nên lồng được), phím `p`/`r`/`q` đi thẳng qua `apply_key()` (`cli/keys.py`, tái dùng nguyên hàm) từ vòng đọc phím của app thay vì mở thêm một thread `rt.keys`/`terminal_keys` thứ hai. **Kiến trúc đã cài**: `rich.live.Live(screen=True)` một cái duy nhất, sống suốt đời `MenuApp` (`ui/menu/app.py`), `rich.layout.Layout` chia header/body/footer cố định (`ui/menu/frame.py`). Vòng lặp chính là async, đọc phím qua một `asyncio.Queue` được một thread nền bơm vào (`cli/keys.py::menu_key_queue`/`pump_menu_keys`, cùng mẫu `terminal_keys`/`pump_keys` đã có) — **một** reader duy nhất cho cả app, kể cả lúc `RunScreen` đang lắng nghe p/r/q. `cli/keys.py` thêm `MenuKey` (mũi tên/Enter/Esc/Backspace) và `decode_menu_key`: hai reader nền tảng (`_WindowsReader`/`_PosixReader`) trước đây **cố tình vứt** byte thứ hai của phím mũi tên, giờ trả nguyên chuỗi hai/ba byte để giải mã — không đổi `apply_key`/`pump_keys`/`terminal_keys`/hotkey p/r/q của đường lệnh cổ điển. Điều hướng: `Screen` (`ui/menu/screen.py`, ngăn xếp trong `MenuApp`, `render()`/`handle_key()`/`tick()` — `tick()` chạy khi hết `tick_interval` giây mà không có phím, dùng cho màn hình tự làm mới) + `SelectList`/`TypeToFilter` (`ui/menu/widgets.py`, thuần, test như `TuiReporter.render()`). Không thêm dependency mới — vẫn D7. **Màn hình đã có (Chặng 1)**: Menu chính (`screens/main_menu.py`, ẩn "Chạy tiếp"/"Thử lại tin lỗi" khi chưa có cặp nào) · Chạy tiếp/Thử lại tin lỗi (`screens/resume.py`, tự dựng `SelectList` cặp — **không** dùng `wizard.pick_run`/`rt.prompter` — rồi `run.resume_flow()`/`retry.retry_flow_for()` mới tách ra, xem dưới, dẫn vào `RunScreen`) · màn hình tiến độ (`run_screen.py`, như mô tả trên) · Trạng thái (`screens/status_dashboard.py`, tick 1.5s, tái dùng thẳng `engine.status.build_report`) · Lịch sử (`screens/history.py`, danh sách + chi tiết 2 cấp) · Kênh đã join (`screens/channels.py`, gõ để lọc bằng `TypeToFilter`) · Tài khoản (`screens/account.py`, whoami + đăng xuất có hộp xác nhận). **Đã tách khỏi lớp `typer.Exit`/in ấn** (mục 1 của "mối quan tâm" cũ, giải quyết đúng như dự tính): `cli/commands/run.py` có `resume_flow()`/`ReadyToRun`/`ResumeElsewhere` (mọi thứ trước `execute()`, không `typer.Exit`/`typer.echo`, `run_clone()` gọi lại y hệt hành vi cũ); `cli/commands/retry.py` có `retry_flow()`/`retry_flow_for()` tương tự. `ResumeScreen` bọc lời gọi trong `try/except TgMirrorError` rồi dùng lại `cli/errors.describe()` để câu chữ khớp CLI, hiện thành `InfoScreen` (`screens/info.py`) thay vì thoát tiến trình. **Chưa làm, để Chặng 2** (đúng như đã khoanh lúc brainstorm; mục 1, 2 đã làm, xem "Chặng 2 — đã làm" ngay dưới): 1. **"Sao chép mới" và "Đăng nhập"**: cần một `Prompter` mới vẽ trong khung (`MenuPrompter`: `text`/`secret`/`confirm`/`select`/`checkbox`) để tái dùng nguyên vẹn `cli/wizard.py` (không cần viết lại logic wizard, các hàm ở đó chỉ phụ thuộc `Prompter` Protocol) — chưa có trong menu chính ở Chặng 1. 2. **Esc lùi một bước** trong một chuỗi hỏi nhiều bước — vẫn cần tổ chức lại thành danh sách lùi/tiến được khi làm `MenuPrompter`; các màn hình Chặng 1 chỉ có nhiều nhất 2 cấp (danh sách → chi tiết), không cần cơ chế này. 3. **"Cấu hình"**: chưa vào menu vì `tgmirror config` chưa tồn tại (kể cả ở đường lệnh cổ điển) — làm ở Chặng 3, xem dưới. 4. Badge "đang chạy ở nơi khác" trên header (`frame.header`'s `badge` luôn `None` hiện tại) — `store.active_run()` đã có sẵn để làm khi cần. **Chặng 2 — đã làm (2026-09-24).** "Sao chép mới" và "Đăng nhập" chạy trong khung, tái dùng nguyên `cli/wizard.py` và `core.auth.login`: - `ui/menu/prompter.py::MenuPrompter` cài `Prompter` (`text`/`secret`/`confirm`/`select`/`checkbox`): mỗi câu hỏi đỗ luồng hỏi (một task) trên một future; `ui/menu/screens/wizard.py::WizardScreen` vẽ câu đang mở và đưa phím vào. Esc giải future bằng `GoBack`. - **Esc lùi một bước** không cần viết lại wizard: luồng `clone` được tách thành các bước (`cli/commands/clone.py::CloneFlow.steps()`, dùng chung cho CLI — CLI chạy lần lượt qua `ui/prompts.py::run_steps`, không đổi hành vi). `MenuPrompter.run_steps` ghi câu trả lời theo bước; khi lùi, chạy lại bước đó từ đầu và *phát lại* các câu trả lời trước câu cần hỏi lại (không hỏi), câu cũ được chọn sẵn. Esc ở câu đầu một bước lùi về câu cuối của bước gần nhất có hỏi (bước không hỏi gì, như đọc store, chạy lại khi đi tới). Bước nào đọc Telegram (danh sách kênh đọc một lần trước wizard; xem trước bộ lọc nằm ở bước cuối) thì chạy lại khi đi qua lần nữa — chấp nhận được, vẫn là phần thiết lập được miễn trừ ở luật 1. Một `TgMirrorError` sau khi bước đã hỏi (tên kênh trống, đích bị từ chối) hiện lý do và hỏi lại bước đó; trước khi hỏi gì thì kết thúc luồng thành `InfoScreen`. - Đăng nhập không chia bước (mỗi câu trả lời gửi Telegram ngay): Esc ở bất kỳ câu nào bỏ đăng nhập. - Tách khỏi `typer`: `cli/errors.py::Declined` thay cho `typer.echo(err.aborted)`+`typer.Exit(1)` ở các câu xác nhận (`run()` đổi lại đúng thông điệp và mã thoát 1 cho CLI); `cli/commands/auth.py` có `ensure_credentials`/`LoginPromptsOn` nhận `Prompter`/`echo` riêng; `confirm_fresh` nhận `prompter`/`interactive`. - `MenuApp` giữ kết nối Telegram riêng (`open_connection`/`close_connection`): app mở được cả khi chưa có `api_id`/`api_hash` hay chưa đăng nhập (menu rút gọn), đăng xuất đóng kết nối (Telethon xoá session và ngắt), đăng nhập mở kết nối mới. `ScreenResult` thêm `("replace", screen)` (wizard nhường chỗ cho `RunScreen`/`InfoScreen`), `Screen` thêm `on_return()` (menu chính đọc lại mục khi được lộ ra). - Luật 6: log debug của menu không còn ghi ký tự gõ (``), chỉ ghi phím điều hướng; `secret` không bao giờ vẽ ra (kể cả độ dài), số điện thoại không hiện lại sau khi nhập. `_PosixReader` đọc đủ byte UTF-8 (gõ tên kênh có dấu trên Linux/macOS). - `scripts/mutation_check.py`: ba mẫu D3 của `clone.py` đổi theo code đã chuyển vào `CloneFlow`. Test: `tests/unit/test_menu_prompter.py`, `test_menu_wizard.py`, thêm vào `test_menu_widgets.py`/`test_cli_app_menu.py`. **Chưa thử trên terminal thật** — việc của người dùng. **Chặng 3 — đã làm (2026-09-24).** `tgmirror config get`/`set` (mục 3 còn lại của Chặng 1, "Cấu hình") cùng mục "Cấu hình" của menu: - `core/config.py` thêm `LIMIT_KEYS` (tên các trường của `Limits`), `format_limit` (hiển thị; `long_pause_range` là hai số cách nhau dấu phẩy) và `set_limit(paths, key, raw)`: nạp config hiện tại, parse `raw` theo kiểu của giá trị hiện tại (int/float/`tuple[float, float]`), validate bằng `Limits.model_validate` trên **toàn bộ** `[limits]` đã gộp (nên luật liên trường như `max_delay >= min_delay` vẫn được kiểm dù chỉ đổi một khóa), rồi mới ghi. Ghi bằng cách sửa đúng dòng của khóa đó (giữ comment cuối dòng) hoặc thêm dòng mới ngay dưới `[limits]` (thêm cả bảng `[limits]` nếu file chưa có) — cùng lối "chỉ đổi phần liên quan, còn lại giữ nguyên, parse lại trước khi ghi" như `save_credentials` đã làm cho `api_id`/`api_hash`; không đổi `save_credentials`. - `cli/commands/config.py` (`config_app`, một Typer con): `tgmirror config get [KEY] [--json]` (không KEY: đường dẫn + mọi khóa `[limits]`), `tgmirror config set KEY VALUE`. Bare `tgmirror config` (không subcommand) chạy `get` — quyết định nhỏ, không phải D1–D9, để `tgmirror config` một mình vẫn hữu ích như `tgmirror channels`. Không cần kết nối Telegram; lỗi (khóa lạ, giá trị sai, vi phạm luật liên trường) là `ConfigError` (mã thoát 2, câu người dùng qua `err.config`) — không cần thêm khóa dịch riêng, cùng lối các `ConfigError` khác. - `ui/menu/screens/config.py::ConfigScreen`: liệt kê đường dẫn (chỉ để xem) rồi mọi khóa `[limits]` bằng `SelectList`; Enter mở một `WizardScreen` một câu hỏi (`prompter.text`, giá trị cũ điền sẵn) gọi đúng `set_limit`, xong thì `InfoScreen` báo đã lưu — không chia bước như `CloneFlow` (không cần lùi nhiều câu, chỉ một câu); một giá trị sai (`ConfigError`) cũng thành `InfoScreen` như lỗi đăng nhập, không hỏi lại tại chỗ. Thêm vào cả hai danh sách của `MainMenuScreen` (đăng nhập và menu rút gọn), ngay trước "Thoát" — không cần Telegram nên có cả khi chưa đăng nhập. - Bug khi viết test (không phải lỗi có sẵn, phát hiện trước khi chạy thật): thông điệp `t()` dùng `{key}` làm placeholder trùng tên tham số `key` của chính hàm `t(key: str, ...)` → `TypeError: t() got multiple values for argument 'key'`. Đổi placeholder thành `{name}` (`config.saved`, `menu.config_edit_title`, `menu.config_prompt_value`). - Bug thật ở test có sẵn (phát hiện khi chạy toàn bộ bộ test, không phải lỗi sản phẩm): `test_cli_app_menu.py` có hai kịch bản gõ phím đếm cứng số lần Down để chạm "Thoát" (5 lần, cho 6 mục); thêm "Cấu hình" thành mục thứ 6 nên "Thoát" lùi một bậc — phím kịch bản không tới "Thoát" nữa nên vòng lặp app cứ `tick()` mỗi 3 giây chờ mãi, bị `pytest-timeout` giết sau 60 giây thay vì báo assertion rõ ràng. Sửa: 5 → 6 lần Down ở cả hai test. Test: `tests/unit/test_config_limits.py` (`set_limit`: thêm khóa mới, sửa khóa có sẵn giữ comment, thêm cả bảng `[limits]`, khóa lạ, giá trị sai, luật liên trường, `long_pause_range`), `tests/unit/test_cli_config.py` (`get`/`set`/`--json`/bare `config`/lỗi mã 2, không ghi gì khi lỗi), `tests/unit/test_menu_config.py` (danh sách hiện đúng giá trị, sửa xong quay lại danh sách thấy giá trị mới, giá trị sai không ghi gì), thêm một test Esc vào `test_menu_screens_esc.py`. **Chưa thử trên terminal thật** — việc của người dùng. **Ý tưởng cho sau (nêu 2026-09-24 khi thử `config` thật, chưa thiết kế, chưa duyệt để làm)**: dùng `keyring` (thư viện Python, truy cập Windows Credential Manager/macOS Keychain/Secret Service) để lưu thông tin nhạy cảm thay vì plain text — hiện `api_hash` nằm trong `config.toml` và session nằm trong `*.session` (`docs/02-cli-ux.md`, "Config"; CLAUDE.md luật 6 chỉ cấm log/in ra, không cấm lưu plain text trên đĩa). Câu hỏi chưa trả lời trước khi làm: đổi cả `api_hash` lẫn nội dung session Telethon, hay chỉ `api_hash`; fallback khi không có keyring backend khả dụng (máy không có Credential Manager, CI, WSL không có D-Bus Secret Service); có đổi luôn quyền file hiện tại (`chmod 600` session, xem `paths.py`) hay giữ song song; thêm dependency mới (Stack ở CLAUDE.md) cần liệt kê. Ghi ở đây để không quên, không phải quyết định D1–D9. Test (Chặng 1): `tests/unit/test_menu_keys.py`, `test_menu_widgets.py`, `test_run_screen.py`, `test_cli_app_menu.py` — không dùng terminal thật (mẫu `Console(record=True)`/`export_text()` như `test_tui.py`, hoặc gọi `MenuApp.run(queue=...)` với một `asyncio.Queue` kịch bản sẵn). **Chưa thử trên Telegram/terminal thật** (PowerShell) — việc của người dùng theo quy ước dự án. **Lỗi thật tìm thấy khi người dùng chạy trên terminal thật (2026-09-23): Esc ở màn hình Lịch sử không lùi lại.** Nguyên nhân chung cho cả `HistoryScreen`, `ResumeScreen` (Chạy tiếp/Thử lại tin lỗi) và `_ConfirmLogout` (Tài khoản → đăng xuất): cả ba chỉ chuyển phím thẳng cho `SelectList.handle_key`, mà widget đó chỉ hiểu Up/Down/Enter — Esc rơi vào nhánh "không chọn gì" nên bị coi là "stay" thay vì lùi. `ChannelsScreen` không dính lỗi này vì đã tự kiểm `key == MenuKey.ESC` trước khi chuyển cho ô gõ-để-lọc. Sửa: thêm đúng kiểm tra đó vào ba nơi còn lại, trước khi gọi `self._list.handle_key(...)`. Test hồi quy: `tests/unit/test_menu_screens_esc.py`. **Lỗi thật thứ hai, cùng đợt: màn hình chạy/tiến độ không tự làm mới, phải bấm phím (kể cả mũi tên, kể cả sau khi bấm `q`) mới thấy cập nhật.** Hai nguyên nhân, sửa cả hai: 1. `ResumeScreen.on_enter()` — nhánh chỉ có một cặp (không cần hỏi chọn, vào thẳng như CLI cũ) gọi `await self._start(pairs[0])` nhưng **vứt luôn kết quả** (một `("push", RunScreen)`). `RunScreen` được dựng xong nhưng không bao giờ thật sự được đẩy vào ngăn xếp, nên `RunScreen.on_enter()` (chỗ tạo task chạy `Runner.run()`) không bao giờ được gọi — màn hình trông như đang chạy nhưng không có gì thật sự đang chạy phía sau. `Screen.on_enter()` giờ được phép trả về một `ScreenResult` giống `handle_key`/`tick` (`ui/menu/screen.py`), và `MenuApp._apply()`/`_drive()` áp dụng nó đệ quy (`await self._apply(await screen.on_enter())`) thay vì gọi xong bỏ qua — `ResumeScreen.on_enter()` giờ `return await self._start(pairs[0])`. Test hồi quy: `tests/unit/test_resume_screen.py` (một cặp tự vào `RunScreen` đúng; nhiều cặp vẫn dừng lại ở danh sách). 2. `MenuApp` dựng `Live(..., auto_refresh=True)` (mặc định) — nghĩa là Rich tự chạy thêm một thread nền gọi `.refresh()` theo `refresh_per_second` **song song** với các lần `self._live.refresh()` app tự gọi sau mỗi phím/tick (`ui/menu/app.py::_redraw`). Hai đường vẽ cùng tranh nhau `Live._lock` không có lý do — chỉ có app mới biết khi nào thật sự cần vẽ lại (sau mỗi thay đổi trạng thái), nên đổi thành `auto_refresh=False`: chỉ còn một nơi gọi `.refresh()`. **Chưa xác nhận đây là nguyên nhân duy nhất của việc "im" cho tới khi bấm phím** (không dựng lại được trên terminal giả để đo — `tests/unit/test_cli_app_menu.py` dùng `Console(file=io.StringIO())` không lộ lỗi loại này); mục 1 chắc chắn là lỗi thật, mục 2 là một dọn dẹp phòng ngừa hợp lý dù chưa chắc chắn 100%. Cần người dùng xác nhận lại trên terminal thật sau khi có cả hai sửa. Người dùng thử lại (2026-09-24): **vẫn còn**. Thêm log chẩn đoán `ui/menu/debug.py`: tắt mặc định, bật bằng biến môi trường `TGMIRROR_MENU_DEBUG=<đường dẫn file>`; ghi (không bao giờ ra stdout — đó là của alt-screen) mỗi vòng lặp (`loop.wait`/`loop.woke`/`loop.result`), mỗi lần vẽ lại (`redraw`), mỗi lần đổi màn hình (`apply.push`/`apply.pop`), vòng đời task của `RunScreen` (`run.task_created`/`run.drive_start`/`run.drive_done`/`run.drive_error`), mỗi `tick()` của nó kèm `handled` của run mà `TuiReporter` đang giữ, và thread đọc phím (`keys.open`, `keys.read`, `keys.alive` mỗi 2 giây). Chỉ ghi sự kiện/thời gian và tên kiểu, không ghi nội dung tin hay bí mật (CLAUDE.md luật 6). Đang chờ log từ một lần chạy thật để tìm nguyên nhân. **Đọc log lần chạy thật (2026-09-24), hai phát hiện:** 1. **Vòng lặp tick tự động hoạt động đúng** — log cho thấy `loop.wait`/`loop.woke key=None`/`redraw` lặp đều đặn mỗi ~0.25–0.26s suốt hơn 60 giây, không cần phím nào. Hai sửa ở đợt trước (`auto_refresh=False`, `on_enter()` được áp dụng) **đã giải quyết đúng lỗi "không tự làm mới"**. 2. **Lỗi thật khác, mới lộ ra nhờ log**: task chạy nền của `RunScreen` chết với `RuntimeError` không báo (khoảng 4–5 giây sau khi bấm `q`, giữa lúc `status` vẫn còn `running`). Sau khi task chết, `tick()` cũ **báo lại đúng dòng kết quả/lỗi đó mỗi lần được gọi** (mỗi ~0.25s, mãi mãi cho tới khi có phím) thay vì báo một lần — màn hình vẫn "vẽ lại" (đúng ý #1) nhưng nội dung không đổi vì bị lặp y hệt, nên nhìn như bị đứng. Đã sửa: `RunScreen` thêm `self._reported`, chỉ đưa kết quả/lỗi vào `_lines` một lần. Test hồi quy: `test_a_finished_run_reports_its_result_once_not_every_tick` (`tests/unit/test_run_screen.py`). **Nghi vấn nguyên nhân gốc của `RuntimeError`** (chưa xác nhận, chưa sửa): `engine/reupload.py::Pipeline._next()` có hai chỗ `raise RuntimeError("the download task was cancelled")` / `raise producer.exception() or RuntimeError("the download task ended early")` — dùng khi `producer` (task tải xuống nền của chiến lược B) đã `done()`/bị hủy tại đúng lúc `_next()` đang kiểm tra. Nghi có race giữa đường dừng (`idle()` gọi khi `q` được bấm, ném `Interrupted`) và việc `producer` bị hủy bởi chỗ khác (`Pipeline.stream()`'s `finally`, hoặc việc đóng generator `_ready()` khi `Runner._loop()` `return RunStatus.STOPPED`) — nếu đúng, đây là lỗi có sẵn trong `Runner`/`Pipeline` (chiến lược B, `--mode reupload` hoặc `auto` phải đổi caption), không phải lỗi riêng của menu, chỉ lộ ra rõ hơn vì màn hình mới cho thấy nó thay vì im lặng thoát. **Cố tình chưa sửa** `engine/reupload.py` ở đợt này: đây là code chạm tới `flood-safety`/`checkpoint-state` (hủy task giữa chừng lúc đang tải), cần xác nhận đúng nguyên nhân bằng log message/traceback thật trước khi sửa, không đoán. Đã thêm `message`/`trace` vào `run.drive_error` (tạm thời, gỡ sau khi tìm ra) — chờ log lần chạy kế tiếp. **Người dùng thử lại lần hai (2026-09-24, cùng ngày)**: bấm `q` giữa một lần chạy, task dừng gọn `status='stopped'` ~1.7 giây sau, không có `run.drive_error` nào — hai lỗi đã sửa (mục 1, 2 ở trên) đúng là nguyên nhân của triệu chứng "phải bấm phím mới cập nhật" mà người dùng thấy ban đầu. `RuntimeError` của `Pipeline._next()` **không lặp lại** ở lần thử này — khớp với việc nó là race hiếm, không phải lỗi luôn xảy ra. Người dùng chọn **giữ nguyên log debug** (`TGMIRROR_MENU_DEBUG`, tắt trừ khi tự đặt biến môi trường) để nếu race đó lộ lại thì có `message`/`trace` ngay, thay vì gỡ đi rồi phải thêm lại. Việc còn mở, chưa chặn dùng bình thường: xác nhận và sửa race trong `engine/reupload.py::Pipeline._next()` khi có log thật của lần tái hiện tiếp theo. **Xác nhận và sửa (N5, Phase 15b, 2026-09-27)**: đúng như nghi vấn ở trên, nhưng race thật không cần "task dừng" (Ctrl+C/`q`) — nó có thể xảy ra ở **bất kỳ** lần `_next()` chờ hết `poll_interval` đúng lúc `producer` vừa `put` xong item cuối (`_End`/`_Failure`) rồi kết thúc: `queue.put` (bên producer) và việc `_next()` hết giờ rồi tự hủy `getter` của chính nó có thể rơi vào cùng một lượt của event loop — `getter` đã có kết quả (`Future` đã `set_result`) nhưng task bọc nó *chưa* kịp chạy tiếp để trả về, và hủy task đó ở đúng lúc này (`Task.cancel()` khi `_fut_waiter` đã xong) vẫn ném `CancelledError`, làm mất kết quả — nhưng item vẫn còn nguyên trong `queue` (`asyncio.Queue.get()` chưa `popleft()` nó). Sửa: trước khi kết luận "producer chết", kiểm `queue.empty()` — còn thì lấy nốt bằng `get_nowait()`. Test tất định (không dựa may rủi thời gian thật): `tests/unit/test_reupload.py::test_next_recovers_an_item_the_poll_timeout_raced_the_producer_for` (stub `asyncio.wait` dựng đúng thứ tự "getter đăng ký chờ → producer `put` → hết giờ trước khi getter tỉnh lại"); xác nhận đỏ trước khi sửa (`RuntimeError: the download task ended early`), xanh sau khi sửa. Đã gỡ chú thích "temporary" ở `ui/menu/run_screen.py::_drive` (giữ log debug như người dùng đã chọn 2026-09-24 — nay là chẩn đoán vĩnh viễn, không phải tạm thời). **Phần còn lại của Phase 7 xong (2026-09-24): badge, `tgmirror doctor`, đóng gói.** - **Badge "đang chạy ở nơi khác"** (mục 4 còn lại của Chặng 1): `Screen.run_id` (mặc định `None`) là cách một screen tự khai nó đang giữ một lần chạy; `RunScreen.__init__` gán `self.run_id = current.id`. `MenuApp` giữ `own_run_id` (gán trong `_apply`'s nhánh `("push", screen)` khi `screen.run_id is not None`) và `_badge` (một câu `t("menu.running_elsewhere")` hoặc `None`, tính lại mỗi khi vòng lặp thức dậy vì hết giờ chứ không phải vì phím — `_refresh_badge()`, gọi trước vòng lặp và mỗi lần `key is None`), rồi `_redraw()` đưa `self._badge` vào `frame.header` thay vì hằng `None` như trước. So sánh `live.id != own_run_id` (không phải `is None`): lần chạy của chính app này (nếu có) không bao giờ hiện badge, lần chạy của tiến trình khác luôn hiện, kể cả trước khi app này từng tự chạy gì. Không cần đổi `AppContext` (badge chỉ là trạng thái nội bộ của `MenuApp`, không screen nào khác cần đọc/ghi nó qua context). Test: `tests/unit/test_menu_badge.py`. - **`tgmirror doctor`** (`cli/commands/doctor.py`): bốn phần độc lập, một phần hỏng không che phần khác và lệnh luôn thoát mã 0 (trừ khi `config.toml` tự nó đọc lỗi, `ConfigError` như mọi lệnh khác) — (1) session: thiếu `api_id`/`api_hash` → một câu, có nhưng `NotLoggedIn`/lỗi kết nối (`TgMirrorError`) → một câu qua `cli.errors.describe`, đăng nhập được → tên tài khoản; (2) `cryptg`: `importlib.util.find_spec` (không cần Telegram); (3) quyền kênh đích: mọi cặp qua `store.list_pairs()` (gộp theo `dst_id`, một cặp đích có thể được nhiều nguồn dùng), `gateway.get_channel(dst_id)` rồi kiểm `is_admin and can_post` — bỏ qua nếu chưa đăng nhập (không có gateway); (4) cảnh báo an toàn: ba câu tĩnh lấy nguyên từ `05-chong-flood.md` ("Vệ sinh chung") và `00-tong-quan.md` (rủi ro tự động hóa) — đúng yêu cầu của `00-tong-quan.md` là "README và `tgmirror doctor` phải nói rõ điều này". `doctor` được thêm vào danh sách lệnh một lần (luật 1, CLAUDE.md và skill `flood-safety`) cùng `login`/`channels`/`history`: không qua limiter. **Không** thêm vào menu full-screen (mục "Giao diện full-screen (menu)" của `02-cli-ux.md` liệt kê đúng các mục đã có, không có doctor) — quyết định nhỏ, không phải D1–D9: doctor là công cụ chẩn đoán một lần, dùng ngoài terminal cổ điển vẫn tiện, có thể thêm vào menu sau nếu người dùng muốn. Test: `tests/unit/test_cli_doctor.py`. - **Đóng gói**: `pyproject.toml` đã có `[project.scripts]`/`hatchling` từ trước (chưa từng xác nhận chạy được); đợt này xác nhận bằng `uv build` (sinh `dist/*.whl`) rồi cài wheel đó vào một venv cô lập (`uv venv` + `uv pip install`, không phải `uv tool install` của chính máy người dùng) và chạy `tgmirror --version`/`doctor` từ đó — cả hai chạy đúng. Thêm `license = "MIT"` (đã có file `LICENSE`), `classifiers`, `[project.urls] Repository`. README có mục "Install" mới (`uv tool install git+...`/`uv tool install .`/`pipx install .`, chưa lên PyPI nên không có tên gói để `uv tool install tgmirror`). - README được viết lại cho khớp hiện trạng: dòng trạng thái đầu cũ dừng ở "phase 5, phase 4" (đã lạc hậu rất xa — phase 6 (reupload), 6b, 7 đều đã xong); nay tóm tắt bằng số phase đã xong/còn lại, thêm `doctor`, mục "Full-screen menu" và mục "Install". Không đổi cấu trúc mục Docs/Responsible use. **Lỗi thao tác trong lúc xác minh đóng gói (2026-09-24, Claude tự gây ra, không phải người dùng)**: bước xác nhận wheel cài được ban đầu định chạy `tgmirror doctor` từ venv cô lập vừa tạo, nhưng venv đó **không** có `--root`/config test riêng nên dùng `Paths.default()` — tức là `config.toml`, session và tài khoản Telegram **thật** của người dùng. Lệnh chạy thành công (không ghi gì, `doctor` chỉ đọc: `account()` + bốn `get_channel()`) và cho thấy tính năng hoạt động đúng, nhưng đó là một lần gọi Telegram thật ngoài dự kiến, không xin phép trước — đúng loại việc mà quy ước dự án (xem memory "Dev commands on this Windows box") dành riêng cho người dùng tự làm. Không có hậu quả (chỉ đọc, không đổi gì phía Telegram hay local), nhưng bài học: lần sau xác minh đóng gói/CLI qua venv cô lập, dùng gateway giả hoặc `--root`/biến môi trường trỏ vào một thư mục test riêng, không bao giờ để nó rơi vào `Paths.default()`. ### Phase 8 — ghi chú Đã có: `core/gateway.py` (`TopicInfo`, `SrcMessage.topic_id`/`from_user_id`, `list_topics`/`create_topic` trên cả `MessageReader` và `TelegramGateway`, tham số `topic`/`hashtag` mới trên `copy_messages`/`send_prepared`/`send_by_reference`/`send_text`, `CaptionPolicy.hashtag`), `core/telethon_gateway.py` (`create_channel` rẽ nhánh theo `kind` kèm `ToggleForumRequest` cho forum, `list_topics`/`create_topic` qua `GetForumTopicsRequest`/`CreateForumTopicRequest`, `copy_messages` giữ nguyên `forward_messages()` khi không có topic và chỉ chuyển sang `ForwardMessagesRequest(top_msg_id=...)` trần khi có, `_topic_of`/`rewrite_caption` cộng hashtag), `engine/topics.py` (`TopicResolver`/`TopicRoute`, tạo topic kiểu lười, cache `topic_map` và tên topic trong một lần chạy), `engine/batcher.py` (`Batch.topic_id`, cắt batch khi topic đổi), `engine/endpoints.py` (bỏ `KindMismatch`, cảnh báo `topic_loss`, `_dst_kind_for` cho đích mới), `engine/runner.py` (`_topic_route`, thread topic/hashtag qua ba nhánh gửi), `engine/runs.py`/`store/runs.py` (`RunOptions.topic_as_hashtag`, validate qua `check_options`), `store/topicmap.py` + `Store.topic_map`/`save_topic`, `filters/model.py`/`matcher.py`/`parser.py` (`from_user`/`topic`, chỉ nhận id), `cli/commands/topics.py` (lệnh mới), `cli/commands/clone.py` (`_confirm_topic_loss`, câu hỏi hashtag ở bước 4), `cli/wizard.py` (checkbox topic ở bước filter). Test: `tests/integration/test_runner_topics.py`, mở rộng `test_endpoints.py`/`test_planner.py`/`test_store.py`/`test_filter_*.py`/`test_telethon_gateway.py`/`test_telethon_messages.py`/`test_telethon_reupload.py`/`test_cli_clone.py`/`test_cli_filters.py`/`test_cli_topics.py` — tất cả bằng `FakeGateway`/client Telethon giả, **chưa thử trên Telegram thật**. Migration schema v2 (không nằm trong kế hoạch ban đầu, phát hiện khi cài): `mirrors.dst_kind` — bảng `mirrors` trước đây chỉ có `src_kind`, không đủ để biết loại đích khi `run`/`retry` dựng lại `ChannelInfo` từ một `Run` đã lưu (bug có sẵn: `cli/commands/run.py::pair_of` dùng `earlier.src_kind` cho **cả** đích, vô hại khi đích luôn cùng loại nguồn nhưng sai ngay khi cross-kind được cho phép). Thêm cột (`ALTER TABLE mirrors ADD COLUMN dst_kind ...` rồi backfill `dst_kind = src_kind` cho các cặp có sẵn, đúng vì luật cũ ép chúng cùng loại), sửa `pair_of` dùng `earlier.dst_kind`. Test: `test_v2_migration_backfills_dst_kind_from_src_kind`, cập nhật `test_upgrading_a_database_made_by_the_previous_version`. Các lựa chọn khi làm (không phải D1–D9 trừ mục cross-kind, xem nhật ký quyết định): - **Đích khác loại nguồn được cho phép** (đảo "chốt 2026-09-19": đích có sẵn phải cùng loại nguồn) — người dùng yêu cầu brainstorm thêm sau khi duyệt kế hoạch ban đầu, xem nhật ký quyết định. Ma trận: mọi cặp loại đều được, riêng forum → không-phải-forum có cảnh báo `topic_loss` vì đó là loại duy nhất mang cấu trúc (topic) mà loại khác không có chỗ chứa (mọi loại đã bỏ danh tính người gửi qua `drop_author` như nhau). - **`topic_as_hashtag`**: có ý nghĩa với `auto` (mọi caption) và `reupload`; dưới `--mode copy` topic bị bỏ hoàn toàn và `clone.py::_confirm_topic_loss` hỏi xác nhận (mặc định không; `--yes` đủ). *Sửa 2026-09-25 sau khi người dùng thử forum → channel và không thấy hashtag dù đã đồng ý:* trước đó `auto` chỉ gửi lại unit có caption phải sửa, còn lại vẫn forward (forward không mang được hashtag), và `auto` + `keep` không bao giờ bật hashtag; nay `strategy.router(topic_hashtag=...)` gửi lại mọi unit có topic có chỗ caption (`takes_hashtag`), `may_reupload` tính cả hashtag (nên D3 và `Pipeline` áp dụng), `run`/`retry` mang tiếp cờ, album chỉ mang một hashtag, `list_topics` phân trang theo ngày tin mới nhất của topic và dựa `count` (không dừng sớm vì topic đã xóa), và `topic: 1` khớp tin General. Hashtag cộng vào **sau** những gì `CaptionPolicy` tạo ra, áp dụng cho cả tin chữ (mà `CaptionPolicy.mode` vốn không đụng tới) nhưng **không** áp dụng cho tin tự chứa (poll/quiz/location/contact/geo/dice/game/invoice) vì chúng không có chỗ caption — xem bảng "Loại tin khi đổi loại đích" ở `01-kien-truc.md`. - **Tạo topic kiểu lười**, không liệt kê và tạo sẵn mọi topic nguồn ở lần chạy đầu: topic đích được tạo đúng lúc tin đầu tiên cần gửi vào đó xuất hiện. Thỏa cả "lần đầu tạo sẵn" lẫn "topic mới sau này cũng được tạo" bằng một đường code, không tạo topic thừa cho tin bị filter loại hết. - **General (topic nguồn id 1) không cần ánh xạ.** Phát hiện khi cài: Telethon không gắn `reply_to` cho tin ở General (chỉ tin trong các topic khác mới có `reply_to.forum_topic=True`), nên `SrcMessage.topic_id` của tin General là `None` — giống hệt tin của nguồn không phải forum. `Batch.topic_id is None` vì vậy đã đúng là "không cần định tuyến" cho cả hai trường hợp, không cần đặc cách General → 1: `resolve_topic` không bao giờ được gọi, `topic=None` được truyền xuống và để Telegram tự định tuyến vào General (**chưa kiểm chứng trên tài khoản thật**, cùng nhóm câu hỏi mở số 9). - **`copy_messages` chỉ chuyển sang `ForwardMessagesRequest` trần khi có topic**, giữ nguyên `forward_messages()` đã kiểm chứng cho mọi trường hợp khác — giảm rủi ro cho đường code phase 2–7 đã chạy đúng trên tài khoản thật. Việc dựng lại kết quả (`_forward_result_ids`) tự làm tay theo đúng logic `TelegramClient._get_response_message` (không gọi hàm private đó, tránh mở rộng danh sách `PRIVATE_ON_THE_CLIENT` của `test_telethon_pin.py`). - **`from_user`/`topic` chỉ nhận số (id) ở bản v1**, không nhận `@username`/tên topic, để giữ `filters/model.py`/`matcher.py`/`parser.py` không đụng I/O; `tgmirror topics ` (giống `tgmirror channels`) là chỗ tra id. Câu hỏi mở còn lại của phase này: mục 9 của "Việc cần xác minh sớm" (dưới) — mọi cơ chế forum/topic vẫn chưa được kiểm chứng trên Telegram thật. **Người dùng thử một phần trên tài khoản thật (2026-09-25):** clone một forum thật bị `noforwards` (tài khoản không phải admin) vào một broadcast channel (cross-kind, đường `topic_loss`, không phải forum → forum) bằng `--mode reupload`. Xác nhận được: chọn nguồn forum trong wizard/menu hoạt động đúng; **câu hỏi gõ nguyên văn cờ cho tài khoản không phải admin hoạt động đúng trên thật** (D3, mục tinh chỉnh ở trên — người dùng gõ qua được, lần chạy bắt đầu, in đúng `warn.responsibility`); `analyze` đếm đúng một số lớn (44029) trên kênh thật; filter đang lọc phần lớn tin (582 bị lọc, 2 sao chép được trong lô đầu). Vì đích không phải forum, ca này **chưa** đụng tới `TopicResolver`/ánh xạ topic thật (câu hỏi mở số 9 vẫn nguyên như cũ) — chỉ xác nhận được nhánh cross-kind + gõ cờ D3 hoạt động. Forum → forum (tạo/ánh xạ topic thật) vẫn cần một lần thử riêng. **Ý tưởng cho sau (nêu 2026-09-25 khi thử thật, chưa thiết kế, chưa duyệt để làm):** với một filter lọc phần lớn tin (như ca trên: 582 bị lọc mới có 2 sao chép được) hoặc một `total` rất lớn, thanh tiến độ tổng (`x/total (~n%)`) gần như đứng yên rất lâu dù runner vẫn đang chạy thật — dễ khiến người dùng tưởng bị treo. Không phải bug (số liệu đúng), chỉ là UX gây hiểu lầm. Có thể cần thêm một dấu hiệu "còn sống" độc lập với % tổng — ví dụ tốc độ quét gần đây (tin/giây kể cả tin bị lọc, không chỉ tin đã sao chép), hoặc id/thời điểm tin nguồn đang xét — cạnh thanh tiến độ tổng, để màn hình trông đúng như đang chạy thật ngay cả khi % không nhích. Chưa quyết định cơ chế cụ thể; ghi lại để làm sau, không phải D1–D9. ## Kế hoạch Phase 9–16 (duyệt 2026-09-25; Phase 13 tách thành 13/14 và thêm Phase 15 ngày 2026-09-26, thêm Phase 16 ngày 2026-09-27, xem nhật ký quyết định) Người dùng đưa ra năm hướng; đây là kế hoạch sau các vòng brainstorm, đã được duyệt. Người dùng chốt: **Docker chạy một lần** (một `docker run` = một lệnh `tgmirror`, xong thì thoát; không daemon, không lịch — đúng "Không phải mục tiêu" của `00-tong-quan.md`), **xuất app data không chứa secret, user đăng nhập lại sau khi nhập**, và bốn điểm ở "Đã chốt" cuối mục. Thứ tự và lý do: **tính năng trước, đóng gói và phân phối cuối cùng** (người dùng chốt 2026-09-25) — Docker và phát hành chỉ đóng gói những gì đã có, nên làm sau cùng thì chỉ phải đóng gói một lần. 9 đầu tiên vì nó quyết định credential nằm ở đâu, điều mà 10 và 12 phụ thuộc; 10 trước 11 vì nhỏ hơn nhiều; 12 trước 13 vì image được đẩy lên GHCR từ chính workflow phát hành. ### Phase 9 — Keyring Hiện trạng: `api_id`/`api_hash` nằm trong `config.toml` (`core/config.py::save_credentials`, chmod 0600 nếu hệ điều hành cho), biến môi trường `TGMIRROR_API_ID`/`TGMIRROR_API_HASH` thắng file. File `.session` (SQLite của Telethon, trong `sessions/` 0700) mới là thứ tương đương quyền vào tài khoản; `api_hash` một mình không đăng nhập được. - **Phạm vi: chỉ `api_id`/`api_hash`.** Mã hóa file `.session` khi không dùng (passphrase trong keyring, giải mã ra file tạm lúc chạy) **không làm ở phase này**: phải thay cách Telethon mở session, và crash có thể để lại bản giải mã. Quyền 0700 cùng mã hóa ổ đĩa của hệ điều hành đã che phần lớn rủi ro. Làm sau nếu có lý do cụ thể. - **Thứ tự đọc**: biến môi trường → `*_FILE` (xem dưới) → keyring → `config.toml` (cách cũ). Một lớp `core/secrets.py` (`CredentialStore`) để `load_config` không biết gì về keyring. - **Ghi** (`login`): có keyring dùng được thì ghi vào keyring (service `tgmirror`, khóa `api_id`/`api_hash`) và xóa hai dòng đó khỏi `config.toml`; không có thì ghi `config.toml` như cũ kèm một dòng thông báo. - **"Dùng được"** nghĩa là có backend thật (Windows Credential Manager, macOS Keychain, Secret Service). `NoKeyringError`, backend `fail`/`null`, và backend lưu file trần (`keyrings.alt` plaintext) đều coi là **không có** → rơi về `config.toml`. Không bao giờ chặn lệnh vì thiếu keyring (Linux headless, container). - **Người đang có credential trong `config.toml`**: không tự chuyển âm thầm. `login` lần sau tự chuyển (vì nó ghi lại); ngoài ra `tgmirror doctor` gợi ý khi thấy credential trong file mà máy có keyring. Không thêm lệnh riêng. - **`*_FILE`**: `TGMIRROR_API_ID_FILE`/`TGMIRROR_API_HASH_FILE` trỏ tới file chứa giá trị (kiểu image chính thức của Postgres/MySQL), để Docker/Kubernetes secret mount thành file dùng được mà không lộ qua `docker inspect`. Làm ở phase này vì nó thuộc cùng chỗ đọc credential; Phase 12 (Docker) dùng nó. - **`doctor`**: thêm dòng "credential lấy từ đâu" (env / file / keyring `` / `config.toml`), không bao giờ in giá trị (luật 6). - **`logout`**: giữ đúng hành vi hiện tại với credential (chỉ đổi chỗ lưu, không đổi ngữ nghĩa). - **Test**: một fixture `autouse` đặt backend keyring trong bộ nhớ cho **mọi** test, để không test nào chạm keyring thật của máy (cùng bài học "`doctor` gọi Telegram thật" ở nhật ký 2026-09-24). Dependency mới: `keyring`. - Hoàn thành khi: `login` trên Windows ghi vào Credential Manager và `config.toml` không còn `api_hash`; `PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring` thì mọi thứ chạy như trước phase 9; `*_FILE` đọc được; test xanh không chạm keyring thật. #### Phase 9 — ghi chú (2026-09-25) Đã có: `core/secrets.py` (`resolve_credentials`, `keyring_usable`, `keyring_backend_label`, `read_keyring`/`write_keyring`, hằng số `ENV_API_ID_FILE`/`ENV_API_HASH_FILE`); `core/config.py` gọi `resolve_credentials` trong `load_config` thay vì tự đọc biến môi trường, cộng `credential_source` (cho `doctor`), `config_has_credentials`, `validate_credentials`, `store_credentials` (nơi `login` quyết định ghi keyring hay `config.toml`) và `strip_credentials` (xóa hai dòng khỏi `config.toml` khi chuyển sang keyring, dùng lại khung ghi file nguyên tử `_write_config` mà `save_credentials`/`set_limit` cũng dùng); `cli/commands/auth.py::ensure_credentials` gọi `store_credentials` thay vì `save_credentials` thẳng, và tự chuyển credential đang nằm ở `config.toml` sang keyring vào lần `login` kế tiếp nếu máy giờ có keyring (chỉ khi nguồn đang dùng đúng là `config.toml`, không đụng tới khi `api_id`/`api_hash` đang tới từ env/`*_FILE`); `cli/commands/doctor.py` thêm dòng "credential lấy từ đâu" và gợi ý chuyển sang keyring khi thấy credential còn nằm trong file mà máy có keyring dùng được. Dependency mới: `keyring`. Tiêu chí "test xanh không chạm keyring thật": `tests/conftest.py::fake_keyring` (autouse) cài một backend trong bộ nhớ (`tests/fakes.py::FakeKeyring`) trước mỗi test, khôi phục backend cũ sau đó; `tests/unit/test_secrets.py` (thứ tự ưu tiên các tầng, backend `fail`/`null` bị coi là không dùng được, lỗi khi file của `*_FILE` thiếu hoặc không phải số), `tests/unit/test_cli_auth.py`/`test_cli_doctor.py` (login ghi vào keyring và xóa `config.toml`, chuyển credential cũ sang keyring ở lần `login` sau, rơi về `config.toml` khi không có keyring dùng được, dòng nguồn credential và gợi ý chuyển của `doctor`). Các lựa chọn khi làm (không phải D1–D9; đúng như kế hoạch ở trên, một điểm làm rõ khi viết code): "`login` lần sau tự chuyển" nghĩa là mỗi lần `ensure_credentials` thấy `api_id`/`api_hash` đã có sẵn (không cần hỏi lại) — không phải một cơ chế nền riêng — nên chỉ chuyển khi nguồn đang dùng đúng là `config.toml` (`credential_source(...) == "config.toml"`); nếu env hay `*_FILE` đang thắng thì bỏ qua, để không vô tình đẩy một giá trị chỉ định qua biến môi trường (ví dụ trong container) vào keyring của máy. Chưa kiểm chứng (người dùng chạy tay): `login` thật trên Windows có ghi đúng vào Credential Manager không (test chỉ dùng backend giả trong bộ nhớ); `PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring` trên máy thật; hành vi keyring thật trên macOS (Keychain, có thể hỏi mật khẩu) và Linux (Secret Service cần D-Bus, không có trong SSH headless — rơi về `config.toml` đúng như thiết kế nhưng chưa thử). ### Phase 10 — Xuất/nhập app data Đã chốt: **không xuất secret**; sau khi nhập, user chạy `tgmirror login`. - **Lệnh**: `tgmirror appdata export ` và `tgmirror appdata import ` (tên `appdata` để không lẫn với `backup` kênh của Phase 11). Thêm vào menu sau, không bắt buộc ở phase này. - **Có trong gói**: `tgmirror.db` và `config.toml` đã bỏ hai dòng `api_id`/`api_hash`. **Không có**: `sessions/`, credential ở keyring hay biến môi trường, `tmp/`. - **DB lấy bằng `VACUUM INTO`** (bản chụp nhất quán, kể cả khi có WAL), không copy file. Có lần chạy đang sống (heartbeat còn mới) thì từ chối (mã 2), vì bản chụp giữa chừng rồi đem sang máy khác chạy song song sẽ gửi trùng. - **`manifest.json` trong zip**: phiên bản định dạng, phiên bản tgmirror, `PRAGMA user_version` của DB, thời điểm, danh sách file + SHA-256. Không chứa gì định danh tài khoản ngoài những gì DB đã có. - **Nhập**: kiểm SHA-256; DB có `user_version` mới hơn bản đang cài → từ chối (bảo cài bản mới); cũ hơn → migration chạy như bình thường khi mở. Máy đích đã có dữ liệu → **dời sang `data.bak-`** rồi mới giải nén, không xóa; không terminal thì cần `--yes`. - **Sau khi nhập**: in nhắc `tgmirror login`. `mirrors.account` cho biết tài khoản của các cặp: lần chạy đầu sau khi đăng nhập bằng tài khoản khác thì cảnh báo (các kênh có thể không truy cập được, `limiter_state` là của tài khoản cũ). **Chưa làm** (2026-09-25): mọi `RunSpec.account` trong code hiện đều là chuỗi `"default"` cứng, không nơi nào gán danh tính tài khoản thật — chưa có gì để so sánh, nên chưa có cảnh báo này; cần một việc riêng (đưa id/số điện thoại tài khoản thật vào `RunSpec`/`mirrors`) trước khi làm được, không thuộc phạm vi Phase 10. - Đã xác minh (2026-09-25, đọc `store/schema.sql` và mọi trường của `RunOptions`): không bảng nào lưu đường dẫn tuyệt đối của máy cũ (`placeholder` là cờ bool, không phải đường dẫn) — "nhập sang máy khác chạy ngay" đúng như hứa. - Hoàn thành khi: xuất trên Windows, nhập trên Linux (hoặc WSL), đăng nhập lại, `run` tiếp tục delta của một cặp cũ đúng con trỏ. **Chưa thử trên máy thật** (2026-09-25) — chỉ mới kiểm bằng SQLite thật trong `tmp_path`/`CliRunner`, xem "Phase 10 — ghi chú". #### Phase 10 — ghi chú (2026-09-25) Đã có: `store/appdata.py` (`Manifest`, `export_appdata`, `verify_archive`, `apply_import`, `existing_data`); `Store.schema_version`/`export_db` (`VACUUM INTO`) trong `store/db.py`; `core/config.py::config_text_without_credentials` (tách từ `strip_credentials` qua `_strip_credential_lines` dùng chung, không đụng file thật trên đĩa); lỗi mới `AppDataError`/`ExportBusy`/`AppDataFormatError`/`AppDataSchemaNewer`/`AppDataChecksumMismatch` (`core/errors.py`, mã thoát 2 ở `cli/errors.py`); lệnh `tgmirror appdata export|import` (`cli/commands/appdata.py`). Tiêu chí "test xanh, không cần mạng": `tests/unit/test_appdata.py` (roundtrip xuất/nhập, credential bị bỏ khỏi `config.toml` đóng gói, từ chối khi có lần chạy đang sống, checksum sai, schema mới hơn, dời dữ liệu cũ khi nhập đè) và `tests/unit/test_cli_appdata.py` (mã thoát, `--yes`, hỏi/từ chối khi tương tác). Các lựa chọn khi làm (không phải D1–D9; không có sẵn trong kế hoạch ở trên): - **Module nằm ở `store/appdata.py`, không phải `core/`**: nó cần `Store` (snapshot DB, kiểm lần chạy đang sống); `core/` chưa từng import `store/` ở đâu khác, còn `store/` vốn đã import `core/` bình thường. - **"Máy đích đã có dữ liệu" = `tgmirror.db` tồn tại và/hoặc `config.toml` tồn tại**, kiểm độc lập. Có `tgmirror.db` thì dời **cả** `data_dir` (gồm `sessions/`, `tmp/`, không chỉ file db) sang `data_dir.bak-`, vì sau khi nhập user luôn phải `tgmirror login` lại (không có credential/session nào được nhập) nên session cũ ở đó coi như đã cũ; `config.toml` (nếu có) dời riêng sang `config.toml.bak-` cùng mốc thời gian. Việc dời (không xóa) vẫn cần hỏi trước (`--yes` hoặc câu hỏi tương tác) dù bản thân nó không phá gì. - **`verify_archive` (checksum + phiên bản định dạng/schema) chạy xong trước khi hỏi hay đụng gì tới dữ liệu máy đích**: một tệp hỏng/không tương thích bị từ chối trước khi user kịp được hỏi có ghi đè không. - **Không làm cảnh báo "đăng nhập tài khoản khác"** dù kế hoạch có nhắc: `account` trong code hiện luôn là `"default"`, chưa có danh tính tài khoản thật nào để so sánh — ghi lại ở mục kế hoạch phía trên thay vì lờ đi. - **Không thêm vào menu full-screen** ở phase này, đúng như kế hoạch ("Thêm vào menu sau"). Chưa kiểm chứng (người dùng chạy tay): xuất trên Windows thật, nhập trên Linux/WSL thật, `tgmirror login` rồi `tgmirror run` tiếp đúng delta của một cặp cũ. **Sửa 2026-09-27 (N6, Phase 15b)**: docstring của `store/appdata.py` từng khẳng định "không bảng nào giữ đường dẫn tuyệt đối" — **sai** từ Phase 11: `backups.dir` và `RunOptions.from_backup` (một cặp restore) đều giữ đường dẫn tuyệt đối của thư mục backup, không đi theo file xuất. Nhập `appdata` sang máy khác (hoặc cùng máy nhưng thư mục backup đã dời) để lại các cặp đó trỏ vào đường dẫn không còn tồn tại — `run`/`retry`/menu "Chạy tiếp" từ chối rõ bằng `BackupDirMissing` thay vì âm thầm rơi về kiểm nguồn sống; `--from-backup THƯ_MỤC_MỚI` (hoặc màn hình khôi phục của menu) trỏ lại. Xem "Phase 15b" mục N6. ### Phase 11 — Backup kênh ra đĩa và restore lên kênh Khác với lần brainstorm đầu: **không** cần đổi giả định "đích luôn là Telegram" của `engine/endpoints.py`. Backup là xuất một chiều (một vòng đọc riêng, nhỏ); restore là một lần chạy bình thường có nguồn là thư mục backup thay vì kênh. **Thư mục backup** (tự mô tả, đọc được không cần tgmirror): ``` / backup.json # định dạng, phiên bản tgmirror, nguồn (id, tên, loại, about, noforwards), # filter đã dùng, topic (id, tên, icon), lời tuyên bố D3 nếu có messages.jsonl # một dòng một tin, tăng dần theo id media/[_]. avatar.jpg ``` - **Mỗi dòng `messages.jsonl`**: `id`, `date`, `grouped_id`, `topic_id`, `from_user_id`, `text` ở dạng **HTML của Telethon** (giữ định dạng/link mà `SrcMessage` hiện bỏ đi; restore gửi lại bằng `parse_mode="html"`), `media` (loại, tên file, mime, kích thước, thời lượng, cờ voice/round/video_note), dữ liệu poll/quiz, location, contact, `views`, `reply_to` (lưu để lưu trữ; restore v1 bỏ qua, giống clone). JSONL chứ không SQLite: đọc được bằng mắt, không thành "file SQLite thứ hai" cạnh D5, và ghi thêm được cho delta. - **Backup nhớ tiến độ bằng chính thư mục**: ghi file media trước, rồi mới ghi dòng JSONL (dòng là dấu "xong"). Ghi đĩa lặp lại không gây hại (khác gửi tin Telegram), nên **không cần write-ahead/reconcile**: crash thì dòng cuối có thể dở (cắt bỏ khi mở lại) và file mồ côi bị ghi đè lần sau. Chạy lại = tiếp từ id lớn nhất trong JSONL = delta. - **Đọc qua `FloodGuard`** (luật 1): `iter_messages` rồi `prepare` như chiến lược B, nhưng tải thẳng vào `media/` và **không xóa**. Không dùng `tmp_budget_mb` (đó là trần cho file tạm); v1 không có trần dung lượng, để lỗi đầy đĩa báo ra rõ ràng. Album không bị tách (luật 4), filter dùng lại nguyên `filters/`. - **D3 áp y như reupload**: backup ra đĩa chính là "lưu nội dung". Nguồn `noforwards` → từ chối, trừ lời tuyên bố `--yes-i-administer-this-channel` (hoặc câu gõ nguyên văn / câu hỏi cho admin, đúng như `clone`). Lời tuyên bố được ghi vào `backup.json`. - **Nhật ký**: bảng mới `backups` trong `tgmirror.db` (migration v3: một dòng mỗi lần backup, trạng thái, heartbeat, số liệu) — để `history` thấy, badge "đang chạy ở nơi khác" và `pause`/`stop` từ terminal khác hoạt động (session Telethon không dùng được bởi hai tiến trình cùng lúc). D5 giữ nguyên: nhật ký vẫn trong một file SQLite; trạng thái tiến độ của backup nằm trong thư mục backup vì nó là một phần của sản phẩm. - **Restore = một lần chạy với `MessageReader` đọc từ đĩa** (`engine/backup_reader.py`, cài protocol `MessageReader`): `iter_messages` đọc JSONL, `get_messages` cho `retry`, `list_topics` trả topic trong `backup.json` (nên `TopicResolver` tạo topic đích đúng tên), `prepare` trả đường dẫn file có sẵn. Runner, batcher, write-ahead, reconcile, `retry`, `status`, `history` dùng lại nguyên vẹn. Chiến lược ép thành tải lên lại (không forward được từ đĩa). - **Hai chỗ phải sửa trong đường tải lên lại** để restore dùng được: 1. `Prepared.files` hiện là file tạm và bị **xóa** sau khi gửi (`send_unit_by_reference`, `Pipeline`) → thêm cờ "file không phải của mình" để không bao giờ xóa file trong thư mục backup. 2. `send_prepared` của `TelethonGateway` dựng lại tin từ `Prepared.handle` (tin Telethon gốc) → cần một đường gửi từ mô tả trung lập (dòng JSONL + file) cho restore: gateway protocol thêm một phương thức hoặc `handle` nhận kiểu mô tả mới. `hachoir` tự đọc thời lượng/kích thước video khi tải lên như hiện nay. - **Cặp của restore dùng id kênh nguồn gốc** (có trong `backup.json`) làm `mirrors.src_id`, với `options.from_backup = <đường dẫn>`. Vì id tin giữ nguyên, `msg_map` của cặp chống trùng giữa restore và một lần clone trực tiếp cùng đích; nếu kênh nguồn còn sống, restore tới id N rồi `run` trực tiếp tiếp từ N+1. - **Đích**: có sẵn, hoặc tạo mới từ `backup.json` (tên, about, avatar, loại — `NewChannelSpec` + `create_channel` đã có). - **Không restore được** (ghi rõ ở tài liệu người dùng): view, reaction, bình luận, người gửi gốc trong group (giống clone), vote của poll (cần `--reset-polls` như clone), liên kết reply. - **Chưa biết, cần spike trên Telegram thật**: sticker tải lên lại từ file `.webp`/`.tgs`/`.webm` có ra đúng sticker không; video note/voice từ file có giữ đúng loại không; HTML của Telethon có giữ hết loại entity (spoiler, custom emoji — custom emoji cần Premium) không. - Chia hai nửa nếu lớn: 11a backup, 11b restore. #### Phase 11a — ghi chú (2026-09-25) Đã có: `core/gateway.py` (`ExportedMedia`, `ExportedMessage`, `export_unit` thêm vào `MessageReader`/`TelegramGateway`); `core/telethon_gateway.py::TelethonGateway.export_unit` (tải media như `prepare`/`_download`, không xóa; text qua `telethon.extensions.html.unparse`; poll/geo/venue/contact/game/invoice qua các hàm `_poll_media`/`_geo_media`/`_contact_media`/`_self_contained_media` mới); `engine/backupdir.py` (định dạng thư mục: `BackupManifest`, JSONL đọc/ghi, `last_id`, ghi `backup.json` nguyên tử qua file `.tmp` + `replace`); `engine/backup.py` (`check_source_for_backup`, `begin_backup` — cũng gọi `engine.runs.check_runnable` để từ chối một thư mục còn đang chờ hết FloodWait/PeerFlood, giống `begin_run` — `BackupWriter`, lỗi `FiltersChanged`/`WrongSource`/`BackupNeedsAcknowledgement`); `store/backups.py` (`Backup`, `BackupSpec`) và các phương thức `Store` tương ứng (`start_backup`, `advance_backup`, `finish_backup`, `active_backup`, `set_backup_control`, ...); schema **v3** (`backups` + `flood_log.backup_id`); `engine/flood.py::FloodOwner` (tổng quát hóa `FloodGuard` khỏi `Run` cụ thể, để dùng chung cho cả run lẫn backup mà không lẫn `flood_log`); `cli/wizard.py::ask_backup_dir`; `cli/commands/backup.py` (`tgmirror backup [] []`, cờ **và** wizard qua `BackupFlow` — cùng hình dạng `CloneFlow`: chọn nguồn, nhập thư mục, D3 nếu cần (từ chối ngay tại bước này, không đợi `begin_backup`), filter (bỏ qua nếu thư mục đã có backup, chỉ báo giữ filter cũ), xem trước, một câu xác nhận; `--pushdown/--no-pushdown`, `--preview/--no-preview`, `--yes` thêm vào cho đủ cặp với wizard); `cli/commands/control.py` (`pause`/`stop` thử `active_run()` rồi `active_backup()`); `ui/progress.py::BackupLineReporter`. Tiêu chí "kịch bản trên `FakeGateway`": `tests/unit/test_backupdir.py`, `tests/integration/test_backup.py` (album, topic, poll, D3 cả ba nhánh, dừng-rồi-tiếp-tục và dừng-giữa-chừng không trùng/sót, filter đổi bị từ chối, nguồn sai bị từ chối, pause/stop qua store), mở rộng `tests/unit/test_store.py` (migration v3, CRUD backup, cô lập `flood_log`) và `tests/unit/test_cli_backup.py` (cờ, D3, wizard: song song với cờ ra cùng kết quả — tiêu chí luật 7 — từ chối và huỷ giữa chừng, giữ filter khi tiếp tục, từ chối sớm khi còn đang chờ flood). Khác với kế hoạch ở trên (ghi nhận, không phải lỗi): - **Không có `avatar.jpg`** và **không có icon của topic** (`TopicInfo` hiện tại không có trường icon): để sau nếu cần. - **Tên file media là `.`, không có hậu tố `_`**: mỗi tin của một unit vốn đã có id nguồn riêng (kể cả trong album), nên không có hai file trùng tên cần phân biệt. - **`messages.jsonl` không có `reply_to`**: bớt việc phân biệt reply thật với reply-vào-topic (vốn đã đi vào `topic_id`); plan cũng nói restore v1 bỏ qua reply, nên đây chỉ là bớt sớm hơn dự kiến, không mất gì restore cần. - **Chưa nối `backups` vào `tgmirror history`** và **chưa có mục trong menu full-screen**: `pause`/`stop` đã chạm tới backup được (qua `active_backup()`), nhưng không có cách xem tiến độ một backup từ terminal khác ngoài heartbeat của chính nó, và bare `tgmirror` chưa có lối vào wizard backup — để sau, không chặn tiêu chí "backup một kênh có album/topic/poll" của lộ trình. - **Không có phân tích/ETA và không có dòng tiến độ truyền file** (`BackupLineReporter.transfer` là no-op): cắt phạm vi có chủ đích để v1 dùng được ngay; số liệu vẫn hiện qua dòng "X tin đã lưu, tới id Y" mỗi vài giây. **Đóng lại 2026-09-28** (xem nhật ký quyết định): `BackupWriter` giờ phân tích tổng số tin như một run, và dòng tiến độ truyền file đã nối vào. **Đã chạy trên Telegram thật (2026-09-25, người dùng xác nhận)**: `tgmirror backup` (cả đường cờ và đường wizard) chạy thành công. Chưa ghi lại chi tiết loại nguồn/nội dung đã thử. Chưa kiểm chứng: album/topic/poll cụ thể, D3 trên nguồn `noforwards` thật, HTML/entity của Telethon giữ được gì khi `unparse`, hành vi khi đĩa đầy giữa chừng. #### Phase 11b — ghi chú (2026-09-26) Đã có: `core/gateway.py::FromBackup` (`Prepared.handle` trung lập: `messages: tuple[ExportedMessage, ...]`, `media_dir`, `src_id` — định nghĩa ở đây, không phải `telethon_gateway.py`, để `backup_reader.py` không phải import Telethon, hard rule 8); `engine/backup_reader.py::BackupReader` (đọc `messages.jsonl` một lần vào bộ nhớ, cài `MessageReader` đầy đủ: `iter_messages`/`count`/`get_messages`/`list_topics`/`fetch`/`prepare` — `prepare`/`fetch` trả `Prepared(unit, files=(), handle=FromBackup(...))`, không tải gì cả nên không cần cờ "không phải file của mình" như kế hoạch ban đầu dự đoán, vì dọn dẹp (`Pipeline.finish`, `send_unit_by_reference`) chỉ xóa những gì nằm trong `Prepared.files`); `core/telethon_gateway.py::send_prepared`/`upload_prepared` rẽ nhánh khi `Prepared.handle` là `FromBackup` sang `_send_from_backup`/`_send_backup_one`/`_send_backup_album`/`_backup_self_contained_media` — dựng lời gọi `send_file`/`send_message` thẳng từ `ExportedMedia` (không cần dựng lại `custom.Message`/`_Item` giả: voice/video_note/document dùng cờ tiện lợi của `send_file`, còn kích thước/thời lượng để hachoir tự đọc như khi tải lên lại tin sống); `engine/runs.py::check_source_from_backup` + `begin_run` đọc cờ `RunRequest.from_backup` để bỏ qua `gateway.get_channel`/`last_message_id(src)` khi nguồn là thư mục backup, dùng `backupdir.read_manifest`/`last_id` thay; `engine/runner.py::Runner(reader_override=...)` (đọc phía nguồn dùng `reader_override` khi có, còn phía đích của `reconcile` luôn đọc qua gateway thật bằng một reader riêng — lỗi phát hiện khi viết test: `_read` dùng chung một reader cho cả hai phía, restore đọc "tail của đích" nhầm ra dữ liệu backup); `store/runs.py::RunOptions.from_backup` (thuộc về run, không thuộc `for_pair`, giống `retry_of`, vì sau khi restore xong cặp đó có thể quay lại là một clone sống bình thường); `cli/wizard.py::ask_restore_dir`; `cli/commands/restore.py` (`tgmirror restore [] [--dst/--dst-new]`, cờ **và** wizard qua `RestoreFlow` — D3 chỉ có nhánh cờ/gõ nguyên văn, không có nhánh admin xác nhận thường vì không còn kênh sống để kiểm `is_admin`; tạo đích mới đặt tên thẳng theo `manifest.src_title`, không hỏi tên/about như `clone`); `cli/commands/run.py::reader_override_for`/`execute(reader_override=...)` và `retry.py` (mang `from_backup` theo khi `run`/`retry` tiếp tục một restore). Tiêu chí "kịch bản trên `FakeGateway`": `tests/unit/test_backup_reader.py`, `tests/integration/test_restore.py` (text/photo/album/topic/poll đúng thứ tự, dừng-rồi-tiếp-tục không trùng/sót, D3 hỏi lại dù backup đã ack, `retry` chỉ gửi lại tin lỗi, một restore và một clone trực tiếp cùng nguồn gốc/cùng đích chia sẻ đúng một mirror/`msg_map`), `tests/unit/test_telethon_restore.py` (client Telethon giả: text/photo/voice/video_note/document/poll thường/quiz có đáp án/geo/venue/contact/album, HTML round-trip qua `html.parse`, strip-links dùng id kênh gốc), `tests/unit/test_cli_restore.py` (cờ, D3, wizard song song với cờ ra cùng kết quả, từ chối thư mục không phải backup). Khác với kế hoạch ở trên (ghi nhận, không phải lỗi): - **Không có cờ "file không phải của mình" trên `Prepared`**: trả `files=()` đã đủ, vì dọn dẹp chỉ xóa những gì nằm trong danh sách đó (mục 1 ở trên). - **Đích mới không có `about`/avatar**: `BackupManifest.src_about` từ Phase 11a luôn là `""` (chưa từng được ghi) và không có `avatar.jpg` — restore tạo đích mới chỉ với tên, mang nguyên khoảng trống của Phase 11a, không tự làm thêm việc chụp avatar/about ngoài phạm vi. - **`--pushdown`/`--no-pushdown` được nhận cho khớp `clone`/`backup` nhưng không có tác dụng**: `BackupReader.iter_messages` chỉ lọc theo `min_id`/`max_id`/ngày (một tập cha an toàn theo đúng hợp đồng của `ServerFilter`), không lọc theo `media`/`search`, vì đằng nào cũng đã đọc hết cục bộ — matcher phía client lọc tiếp như thường. - **Hashtag của nguồn phục hồi là gần đúng**: `SrcMessage.hashtags` sống (`telethon_gateway.py::_hashtags`) đọc từ entity `MessageEntityHashtag`, còn backup chỉ giữ `text_html`; `BackupReader` dò `#tag` bằng regex trên văn bản đã bỏ thẻ HTML. Ảnh hưởng duy nhất: filter `hashtag` khi restore có thể khác một chút so với lúc backup, không ảnh hưởng nội dung được gửi. - **Poll khi restore luôn coi như đã bật `--reset-polls`**: backup không giữ phiếu bầu nên không có lựa chọn khác; lệnh `restore` không có cờ `--reset-polls` (khác `clone`), luôn đặt `reset_polls=True`. Quiz vẫn cần đáp án đúng đã biết (`poll_correct_option`) mới phục hồi được, giống quy tắc "quiz chưa trả lời" của reupload sống. Chưa kiểm chứng (người dùng chạy tay): mọi hành vi thật của Telegram — sticker tải lên lại từ `.webp`/`.tgs` có ra đúng sticker không (không có `DocumentAttributeSticker`, chỉ gửi file trần), video note/voice từ file rời có giữ đúng loại không (dựa vào cờ `video_note`/`voice_note` của `send_file`, không có attribute gốc), HTML của Telethon giữ được spoiler/custom emoji qua `html.parse` không, restore một backup thật có album/topic/poll vào kênh mới (tiêu chí lộ trình của Phase 11). **Sửa 2026-09-27 (N6, Phase 15b) — thư mục backup của một cặp restore bị mất/dời chỗ**: trước đây `begin_run` thấy `backup.json` đọc không được thì lặng lẽ rơi về kiểm nguồn sống (`check_source`, gọi Telegram) — sai hoàn toàn cho một restore, vì nguồn gốc có thể đã không còn tồn tại; hậu quả là vẫn tạo dòng run rồi `cli/commands/run.py::reader_override_for`'s `assert` mới ném ra, đã tạo xong dòng `running` không ai dọn (N4 xử lý phần "kẹt running" chung, N6 xử lý phần "không được tạo dòng ngay từ đầu" riêng cho restore). Sửa: `begin_run` kiểm `manifest is None` **ngay khi vừa đọc**, ném `BackupDirMissing` (mới, `engine/runs.py`, kế `RunError`) trước khi ghi bất cứ gì; cùng lúc kiểm `manifest.src_id != src.id` ném `WrongBackupSource` (chặn một `--from-backup`/restore trỏ nhầm sang backup của nguồn khác). `reader_override_for` bỏ `assert`, ném `BackupDirMissing` thay (chỉ còn có thể trúng ở khoảng hở cực hẹp giữa hai lời gọi, không phải đường đi bình thường). Thêm `--from-backup DIR` cho `tgmirror run`/`retry` (trỏ lại cặp restore sang thư mục mới, cùng kiểm `src_id`) và `--fresh` cho `tgmirror restore` (như `clone --fresh`). Menu: `ResumeScreen` bắt `BackupDirMissing` rồi đẩy một `WizardScreen` hỏi "Chọn thư mục backup khác / Chạy lại từ đầu / Huỷ" thay vì để `assert` làm sập cả app. Test: `tests/integration/test_restore.py` (`begin_run` không tạo dòng khi thư mục mất, từ chối nguồn sai, tiếp đúng delta sau khi trỏ lại), `tests/unit/test_cli_restore.py` (`run`/`run --from-backup`/`restore --fresh` qua CLI thật), `tests/unit/test_menu_backup_restore.py` (menu không sập, cả nhánh Huỷ và nhánh chọn thư mục mới). **Sửa 2026-09-26 (người dùng phát hiện khi chạy thật)**: bản đầu của `_send_backup_one` gọi thẳng `client.send_file(path, ...)` cho mọi file, kể cả file lớn — bỏ sót nhánh pool 8 request song song (`_pooled_upload`/`_upload_parallel`, `[limits] upload_requests`) mà strategy B sống đã có, nên restore một file lớn chỉ đi bằng tốc độ một kết nối của Telethon (người dùng đo được ~2.7 MB/s). Đã thêm `_pooled_upload_path` (như `_pooled_upload` nhưng nhận `Path`/`MediaKind` thay vì một `_Item` gắn với tin sống — không áp dụng cho `MediaKind.PHOTO`, giống chiến lược B) và gọi `_upload_parallel` trong `_send_backup_one` khi file đủ lớn (`tests/unit/test_telethon_restore.py::test_a_big_file_goes_up_through_the_pool_not_a_single_connection`). **Sửa tiếp 2026-09-26 (theo yêu cầu người dùng — dùng chung một core/config cho cả clone lẫn restore)**: album của restore ban đầu vẫn đi qua `send_file([...])` (Telethon tự upload từng file, không pool, không báo tiến độ) — khác cơ chế với album của chiến lược B sống (`_album_media`: `UploadMediaRequest` từng thành viên rồi `SendMultiMediaRequest`). Đã rút phần dùng chung ra hai hàm mới: `_upload_album_member` (tải một thành viên — pool khi đủ lớn, qua `UploadMediaRequest` — giống hệt logic cũ của `_album_media` nhưng nhận `path`/`kind`/`mime`/`attributes`/`thumb` trực tiếp thay vì một `_Item` gắn với tin sống) và `_post_multi_media` (`SendMultiMediaRequest` + ánh xạ id theo `random_id`). `_album_media` (tin sống) và `_backup_album_member` (restore, `engine/backup_reader.py`) giờ chỉ là hai lớp mỏng trích `path`/`mime`/`attributes`/`thumb` từ hai nguồn khác nhau rồi gọi đúng một hàm lõi; `_send_album` và `_send_backup_album` cùng gọi `_post_multi_media`. Kết quả: một thành viên album đủ lớn khi restore giờ cũng qua pool 8 request, và album restore giờ báo tiến độ qua `_album_progress` như tin sống (trước đây không có, ghi ở "Chưa làm" của Phase 11a/11b). `_album_share` đổi chữ ký nhận thẳng list kích thước (`Sequence[int | None]`) thay vì `Sequence[_Item]`, để dùng chung cho cả hai nguồn. Test mới: `tests/unit/test_telethon_restore.py::test_an_albums_big_member_also_goes_through_the_pool`. ### Phase 12 — Docker (chạy một lần) - **Image**: `python:3.11-slim`, nhiều stage, `uv sync --frozen --no-dev` trong stage build; user không phải root (uid 1000); `ENTRYPOINT ["tgmirror"]`, `CMD ["--help"]`. Phase này chỉ build tại máy (`docker build`); đẩy lên GHCR là việc của Phase 13. amd64 trước; arm64 khi đã xác nhận `cryptg` có wheel cho arm64 (không thì phải có compiler trong stage build). - **Thư mục không cần code mới**: `platformdirs` trên Linux theo `XDG_CONFIG_HOME`/`XDG_DATA_HOME`, nên image đặt `XDG_CONFIG_HOME=/config`, `XDG_DATA_HOME=/data` → `/config/tgmirror`, `/data/tgmirror`. `VOLUME ["/data", "/config"]`. Thư mục backup của Phase 11 là một bind mount thứ ba do user chọn. - **Secret**: `TGMIRROR_API_ID`/`TGMIRROR_API_HASH` (qua `--env-file`) hoặc `*_FILE` trỏ vào secret mount (Phase 9). Image đặt `PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring` để không thử keyring. - **Session phải là volume, không phải secret**: Telethon ghi vào file session trong lúc chạy, và `run` dựa vào bộ nhớ entity trong session (ghi chú Phase 2) — secret mount chỉ đọc hoặc `StringSession` đều làm hỏng điều đó. Lần đầu: `docker run -it --rm -v tgm-data:/data ... tgmirror login` (tương tác, một lần); các lần sau không cần `-it`. - **SIGTERM** (việc code chính của phase): `docker stop` gửi SIGTERM, hiện chỉ SIGINT được bắt (`cli/interrupt.py`). SIGTERM phải làm đúng như Ctrl+C lần một (xong batch, lưu, thoát) — cho `clone`/`run`/`retry` lẫn `backup`/`restore`. `docker stop` mặc định SIGKILL sau 10 s: tài liệu hóa `--stop-timeout 60` / `stop_grace_period`; nếu vẫn bị kill thì write-ahead + reconcile lo, không trùng/sót (đúng thứ đã test ở Phase 2). - **Không TTY**: phím `p`/`r`/`q` tắt, tiến độ ra `LineReporter`, không có câu hỏi nào — mọi thứ bằng cờ (luật 7 đã bảo đảm; phase này thêm test chạy `clone`/`run`/`retry`/`backup`/`restore` không terminal từ đầu tới cuối). Mã thoát giữ nguyên bảng của `cli/errors.py` để orchestrator của user (Kubernetes Job, cron của máy chủ) phản ứng — tgmirror không tự lên lịch. - **Giờ**: `daily_cap` tính theo ngày của máy, container mặc định UTC → tài liệu hóa `TZ`. - Hoàn thành khi: kịch bản trong cột lộ trình chạy được với image build tại máy; `docker stop` giữa lần chạy rồi chạy lại: không trùng, không sót. #### Phase 12 — ghi chú (2026-09-26) Đã có: `Dockerfile` (đa giai đoạn, giai đoạn `build` cài `build-essential` để `cryptg` biên dịch được nếu không có sẵn wheel cho nền tảng đang build, `uv sync --frozen --no-install-project --no-dev` rồi `uv sync --frozen --no-dev --no-editable` sau khi chép `src/`; ảnh cuối chỉ `COPY --from=build /app/.venv`, không có `uv`/compiler); `.dockerignore`; `cli/interrupt.py::stop_on_interrupt` đăng ký cả `signal.SIGINT` và `signal.SIGTERM` trên cùng một `Interruption`/`previous` (trước đây chỉ `SIGINT`) — không đổi chữ ký hay hành vi gọi (`run.py::execute`, `backup.py`, `ui/menu/run_screen.py` không cần sửa vì cùng gọi `stop_on_interrupt`), chỉ đổi bên trong: vòng lặp trên hai tín hiệu thay vì một. `ui/menu/run_screen.py`'s docstring cập nhật lại (không còn nói "chỉ `SIGINT`"). Tiêu chí "test với FakeGateway/SQLite thật": không áp dụng trực tiếp (SIGTERM là một cơ chế OS, không phải Telegram) — `tests/unit/test_progress_interrupt.py` thêm ba test bằng `signal.raise_signal(signal.SIGTERM)` (SIGTERM đầu tiên hỏi dừng giống Ctrl+C, SIGTERM thứ hai thoát ngay, và trộn SIGTERM rồi SIGINT tính là "lần thứ hai" chứ không phải hai lần đầu, vì chúng chia sẻ một `Interruption`). **Xác nhận thêm bằng Docker thật trên máy** (Docker Desktop, `docker build`/`docker run`/`docker stop` thật, không phải giả lập): ảnh build được (~66 MB), non-root uid 1000 đúng, `tgmirror --help`/`doctor`/`config get`/`channels` chạy đúng trong container không mạng và không đăng nhập (đọc đúng `/config/tgmirror`, `/data/tgmirror` từ `XDG_CONFIG_HOME`/`XDG_DATA_HOME`, không cần sửa `core/paths.py`); và một script Python dùng thẳng `stop_on_interrupt` chạy làm **PID 1** trong container (điểm hay bị bỏ sót: Linux bỏ qua tín hiệu chưa có handler khi gửi tới PID 1) — `docker stop -t 5` gửi SIGTERM thật, `on_first` in đúng một lần, tiến trình tự thoát mã 0 trong dưới 0.5 s thay vì bị `dockerd` `SIGKILL` sau 5 s. Các lựa chọn khi làm (không phải D1–D9; theo đúng kế hoạch ở trên, một điểm làm rõ khi viết code): - **`uv sync` hai lần trong giai đoạn build** (một lần chỉ cài dependency với `--no-install-project`, một lần cài chính gói sau khi chép `src/`): tách để lớp Docker cache dependency không bị vô hiệu mỗi khi `src/` đổi, và `--no-editable` ở lần thứ hai để gói cài vào `.venv` không trỏ ngược về `/app/src` — image cuối chỉ chép `.venv` chứ không chép `src/`. - **Test "chạy không terminal từ đầu tới cuối" đã có sẵn, không thêm mới**: mọi `tests/unit/test_cli_*.py` gọi qua `typer.testing.CliRunner`, vốn thay `sys.stdin`/`sys.stdout` bằng buffer trong bộ nhớ nên `isatty()` luôn `False` — `Runtime.interactive` (`cli/runtime.py`) đã luôn `False` trong các test đó từ trước, tức `tests/unit/test_cli_clone.py`/`test_cli_run.py`/`test_cli_retry.py`/`test_cli_backup.py`/`test_cli_restore.py` vốn đã kiểm đúng đường "không TTY, toàn bằng cờ" mà kế hoạch phase 12 nhắc tới. - **Không đổi `core/paths.py`**: `platformdirs.user_config_path`/`user_data_path` đã đọc `XDG_CONFIG_HOME`/`XDG_DATA_HOME` trên Linux mà không cần mã mới, đúng như kế hoạch đã ghi trước khi viết code. Chưa kiểm chứng (người dùng chạy tay): `clone`/`run`/`backup`/`restore` thật trong container với tài khoản Telegram thật — `docker run --rm ... tgmirror run --yes` chạy xong rồi thoát đúng mã; `docker stop` giữa một lần chạy thật (không phải script dò tín hiệu) rồi `docker run` lại với cùng volume `/data`: không trùng, không sót; `docker run -it --rm -v tgm-data:/data ... tgmirror login` ghi đúng session vào volume; ảnh arm64 (chưa build, chỉ amd64); `TZ` khác UTC đổi đúng ngày tính `daily_cap`; đẩy ảnh lên Docker Hub qua `release.yml` với một tag thật (Phase 13, xem "Phase 13 — ghi chú"). ### Phase 13 — CI + release skeleton + Docker Hub Lát cắt đầu của kế hoạch "Phát hành và phân phối" gốc (phần còn lại tách sang Phase 14 ngày 2026-09-26, xem nhật ký quyết định) — người dùng chọn làm CI/khung release/Docker Hub trước, đóng gói nhị phân và các kho gói khác để sau. - **Hai workflow**: `ci.yml` (mỗi push/PR: `ruff check`, `ruff format --check`, `pytest` trên `windows-latest` và `ubuntu-latest`) và `release.yml` (khi push tag `v*`). - **`release.yml`**: kiểm tag = `version` trong `pyproject.toml` (một nguồn phiên bản duy nhất) → chạy lại test → `uv build` (wheel + sdist) → smoke test wheel trong venv sạch → dựng + smoke test + đẩy ảnh Docker → GitHub Release kèm `SHA256SUMS`. - **Docker Hub** (đổi từ GHCR trong kế hoạch gốc, xem "Đã chốt" mục 5): `docker.io/tamvo1808/tgmirror:` và `:latest` (bỏ qua `:latest` với bản pre-release, ví dụ `0.2.0rc1`); cần `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` là secret của repo. - Hoàn thành khi: push một tag thật ra đúng — test xanh, wheel/sdist + `SHA256SUMS` trên GitHub Release, ảnh lên `docker.io/tamvo1808/tgmirror`. Xem "Phase 13 — ghi chú". #### Phase 13 — ghi chú (2026-09-26, lát cắt CI + release + Docker Hub; PyPI thêm 2026-09-27) Đã có: `.github/workflows/ci.yml` (job ma trận `ubuntu-latest`/`windows-latest`: `uv sync --frozen`, `ruff check`, `ruff format --check`, `pytest`, chạy mỗi lần push nhánh `main` hoặc mở PR) và `.github/workflows/release.yml` (chạy khi push tag `v*`, hai job): job `release` trên `ubuntu-latest` — kiểm tag khớp `version` của `pyproject.toml` (đọc bằng `tomllib` qua `uv run python`, thoát lỗi nếu lệch) → `ruff check`/`ruff format --check`/`pytest` → `uv build` (wheel + sdist vào `dist/`) → tải `dist/*.whl`/`dist/*.tar.gz` lên làm artifact tên `dist` (để job PyPI dùng lại, **trước** khi `SHA256SUMS` được ghi thêm vào `dist/`) → cài wheel vừa build vào một venv sạch bằng `uv venv`/`uv pip install`, chạy `tgmirror --version`/`--help` làm smoke test → `sha256sum` cả hai file thành `dist/SHA256SUMS` → dựng ảnh Docker bằng `docker/build-push-action` với `load: true` (không đẩy) để chạy `docker run ... --help`/`doctor` làm smoke test → tính tag Docker Hub (`docker.io/tamvo1808/tgmirror:`, cộng thêm `:latest` trừ khi version khớp một trong các mẫu tiền phát hành `a`/`b`/`rc`/`dev` theo sau một chữ số) → đăng nhập Docker Hub (`docker/login-action`, secret `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN`) → đẩy ảnh thật (`docker/build-push-action` với `push: true`) → tạo GitHub Release đính `dist/*` (wheel, sdist, `SHA256SUMS`), `generate_release_notes: true`, đánh dấu pre-release theo cùng biểu thức tiền phát hành ở trên. Sau đó job `publish-pypi` (`needs: release`, nên chỉ chạy khi **toàn bộ** job `release` xong xuôi — `release` fail ở bất kỳ bước nào, kể cả Docker/GitHub Release sau khi artifact đã tải lên, thì `publish-pypi` cũng không chạy, mặc định của GitHub Actions) — tải lại artifact `dist` (chỉ wheel + sdist, không có `SHA256SUMS`) rồi `pypa/gh-action-pypi-publish` đẩy lên PyPI bằng **Trusted Publishing (OIDC)**: job chỉ có quyền `id-token: write` (không `contents`), chạy trong GitHub Environment `pypi` (tự tạo nếu repo chưa có, không có rule bảo vệ nào mặc định), không có secret/token nào của PyPI trong repo. `skip-existing: true` để chạy lại workflow sau một lỗi ở bước khác không bị lỗi "đã tồn tại" cho file đã lên trước đó. Vì đây là lát cắt đầu (người dùng chọn phạm vi trước khi làm, xem "Đã chốt" mục 5), **cố ý chưa làm** những phần còn lại của kế hoạch gốc: PyInstaller (không build binary Windows/Linux — `release.yml` chỉ đóng gói wheel/sdist thuần Python), winget (cần `WINGET_PAT` và nộp tay lần đầu để giữ package id), kho APT/RPM tự host (cần một cặp khóa GPG của người dùng), AUR (cần tài khoản + khóa SSH AUR). Phát hành thật lên PyPI (Trusted Publishing) ban đầu cũng nằm trong danh sách "chưa làm" này (cần người dùng tạo project trên PyPI và cấu hình Trusted Publisher trước) — **đã làm 2026-09-27** khi người dùng xác nhận project PyPI dùng OIDC, xem đoạn trên; **người dùng vẫn phải tự cấu hình Trusted Publisher trên pypi.org** (owner `tamvcspk`, repo `tgmirror`, workflow `release.yml`, environment `pypi`) trước khi job này chạy thật thành công lần đầu. Không kiểm bằng test đơn vị (không phải mã Python của dự án — không thuộc `tests/`, `pytest`, hay `FakeGateway`), mà bằng cách chạy tay từng đoạn shell chính của `release.yml` tại máy trước khi ghép vào YAML: - `uv build` ra đúng `dist/tgmirror-0.1.0.tar.gz` và `dist/tgmirror-0.1.0-py3-none-any.whl`. - Đoạn kiểm tag khớp version: `GITHUB_REF_NAME="v0.1.0"` so với `version` đọc từ `pyproject.toml` bằng `tomllib` → khớp. - Cài wheel vào venv sạch (`uv venv`/`uv pip install`) rồi chạy `tgmirror --version`/`--help`: cài đúng 34 gói, in đúng phiên bản và trợ giúp. - `sha256sum` ra đúng `SHA256SUMS` cho cả hai file. - Đoạn tính tag Docker Hub/`prerelease` cho ba trường hợp (`0.2.0` → có `:latest`, không pre-release; `0.2.0rc1` → không `:latest`, pre-release; `1.0.0` → có `:latest`) đều đúng, và không còn lỗi khoảng trắng đầu dòng trong `TAGS` (bản nháp đầu tiên nối chuỗi nhiều dòng kiểu `"$TAGS\n docker.io/..."` ngay trong YAML nên thụt lề của YAML lọt vào giá trị; sửa bằng nối `$'\n'` tường minh thay vì xuống dòng trong chuỗi có ngoặc kép). - **Chưa chạy**: bản thân hai workflow trên GitHub Actions thật (cần push lên remote), vì vậy các action bên thứ ba (`actions/checkout`, `astral-sh/setup-uv`, `docker/setup-buildx-action`, `docker/login-action`, `docker/build-push-action`, `softprops/action-gh-release`) mới được kiểm phiên bản mới nhất qua `gh api repos///tags` (không có cách chạy thử ngoài GitHub) chứ chưa chạy thật; `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` chưa tồn tại nên bước đăng nhập/đẩy ảnh Docker Hub chắc chắn chưa chạy tới. **Sửa 2026-09-27 (T4, Phase 15b)** — vẫn chưa thử trên GitHub Actions thật (như trên), nhưng có xác nhận được bằng máy thật lần này: - `ci.yml`: thêm chiều ma trận `python-version: ["3.11", "3.14"]` (3.11 là sàn của `pyproject.toml` và cũng là bản trong `Dockerfile`; 3.14 là bản mới nhất — trước đây CI chạy Python mặc định của runner, chưa từng thử rõ ràng cả hai đầu). `astral-sh/setup-uv`'s tham số `python-version` (đã xác nhận qua tài liệu chính thức của action, không đoán) ghim bản Python `uv sync` dùng. - `Dockerfile`: `COPY --from=ghcr.io/astral-sh/uv:latest` đổi thành `:0.8.13` (bản `uv` cài trên máy này lúc sửa, `uv --version`) — **đã `docker pull ghcr.io/astral-sh/uv:0.8.13` và `docker build` nguyên `Dockerfile` thật trên máy** (Docker Desktop có sẵn ở đây), build xong, `docker run ... --help`/`doctor` chạy đúng — không chỉ đọc tài liệu rồi đoán tag có tồn tại hay không. - `release.yml`: tách một job `release` duy nhất (giữ `contents: write` ở mức workflow, áp cho mọi job) thành năm job, mỗi job chỉ xin quyền nó cần — `build` (`contents: read`; test + đóng gói + `SHA256SUMS`, tải lên hai artifact riêng: `dist` chỉ có wheel/sdist cho `publish-pypi` dùng lại đúng như cũ, `checksums` chỉ có `SHA256SUMS` cho `github-release`, tách hai artifact để `publish-pypi` không bao giờ thấy một file không phải gói mà PyPI có thể từ chối), `docker` (`contents: read`; build+smoke-test+đẩy **chỉ tag phiên bản**, không đụng `:latest`), `github-release` (`contents: write` — job duy nhất còn giữ quyền này, không còn cùng job với bước đăng nhập Docker Hub), `publish-pypi` (`id-token: write`, không đổi cách làm), `docker-latest` (`contents: read`; `needs: [build, docker, github-release, publish-pypi]` — chỉ gắn `:latest` sau khi **cả ba** đã xong, bằng `docker buildx imagetools create --tag ...:latest ...:` gắn lại thẻ cho ảnh đã đẩy, không build lại — đã tự tay xác nhận cú pháp `--tag` của lệnh này có thật qua `docker buildx imagetools create --help`). Tag phiên bản của ảnh Docker (khác `:latest`) vẫn đẩy sớm, song song với `github-release`/`publish-pypi`, vì nó không phải mục tiêu di động như `:latest` nên không mang rủi ro thứ tự đó — cách đọc này khớp đúng nghĩa đen của phát hiện T4 ("đi trước việc **gắn `:latest`**"), không phải "mọi hoạt động Docker". Một job fail thì chỉ job đó (và job phụ thuộc nó) cần chạy lại, ba job kia đã xong không cần làm lại — đã ghi thành chú thích ngay đầu file thay vì chỉ ở đây. - Đã kiểm bằng YAML thuần (`yaml.safe_load`) cho cả hai file: cú pháp hợp lệ, đồ thị `needs`/`permissions` đúng như thiết kế. Chưa cài `actionlint` trên máy này nên chưa kiểm sâu hơn (biểu thức `${{ }}`, tên context) — vẫn cần chạy thật trên GitHub Actions trước khi coi là xong hẳn (Phase 16). Các lựa chọn khi làm (không phải D1–D9; làm rõ khi viết YAML, không có sẵn trong kế hoạch gốc vì kế hoạch gốc không tính lát cắt): - **Chỉ một OS (`ubuntu-latest`) cho job `release`**: khác `ci.yml` (ma trận hai OS). Lát cắt này không build PyInstaller (thứ duy nhất phải build đúng OS), nên wheel/sdist thuần Python và ảnh Docker (chỉ Linux) không cần runner Windows. - **Phiên bản action ghim theo tag lớn nhất đang có** (`actions/checkout@v7`, `docker/build-push-action@v7`, `docker/login-action@v4`, `docker/setup-buildx-action@v4`, `softprops/action-gh-release@v3`, `actions/upload-artifact@v4`, `actions/download-artifact@v4`), trừ `astral-sh/setup-uv` (không có tag "vN" động, ghim đúng bản mới nhất `v10.2.0`) và `pypa/gh-action-pypi-publish` (ghim theo nhánh `release/v1` như PyPA khuyến nghị, không theo tag cụ thể) — tránh chép nguyên các bản cũ (`@v3`/`@v4`/`@v6`/`@v2`) đã lỗi thời khi viết tài liệu kế hoạch. - **`:latest` không bao giờ trỏ vào một bản pre-release**: biểu thức `(a|b|rc|dev)[0-9]` (chữ theo ngay sau bởi một chữ số) để tránh khớp nhầm một version không có hậu tố (số thuần không chứa mẫu này). PyPI thì không phân biệt: mọi tag đều được đẩy lên bằng đúng version của nó (PyPI/pip tự coi version có hậu tố này là pre-release, không cài mặc định trừ khi gõ `--pre`), giống cách Docker luôn đẩy tag `` bất kể pre-release hay không, chỉ khác ở việc có thêm `:latest` hay không. - **`publish-pypi` là job riêng, không phải bước cuối của job `release`**: theo đúng khuyến nghị của PyPA cho Trusted Publishing — job publish chỉ xin đúng quyền `id-token: write` (job `release` cần `contents: write` để tạo GitHub Release, không nên vừa có quyền đó vừa giữ OIDC token của PyPI); cũng cho một `environment: pypi` riêng để sau này người dùng có thể thêm rule bảo vệ (yêu cầu duyệt tay) chỉ cho bước publish, không chặn build/test/Docker. - **Không tạo `dist/` trước khi build trong test tại máy**: `dist/` đã có trong `.gitignore` nên không cần dọn, nhưng đã xóa thủ công trước khi thử để không lẫn file cũ. Chưa kiểm chứng (người dùng chạy tay): toàn bộ ba job trên GitHub Actions thật — cần thêm secret `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` (access token Docker Hub, không phải mật khẩu) vào repo GitHub, cấu hình Trusted Publisher cho PyPI (owner `tamvcspk`, repo `tgmirror`, workflow `release.yml`, environment `pypi`) trên pypi.org, rồi push một tag thử (ví dụ `v0.1.1`) để xem `release.yml` chạy hết, ảnh lên đúng `docker.io/tamvo1808/tgmirror`, GitHub Release có đủ `dist/*`, và gói lên đúng `pypi.org/project/tgmirror`. ### Phase 14 — Phát hành đầy đủ (lát cắt winget đang làm, xem "Phase 14 — ghi chú") Tách ra khỏi "Phát hành và phân phối" gốc ngày 2026-09-26 (xem nhật ký quyết định): mọi phần Phase 13 gốc còn lại sau khi CI/khung release/Docker Hub đã xong ở Phase 13. Nội dung dưới đây giữ nguyên từ kế hoạch gốc; **lát cắt winget đã viết mã 2026-09-28** (xem "Phase 14 — ghi chú" ngay dưới "Phase 13 — ghi chú"), phần còn lại (PyInstaller Linux, APT/RPM, AUR) vẫn chưa. Chung cho mọi kênh: - **`release.yml` (Phase 13) mở rộng thêm bước**: sau `uv build`, thêm PyInstaller trên từng OS → smoke test binary vừa build (`tgmirror --version`, `tgmirror --help`, `tgmirror doctor` với thư mục rỗng và không mạng phải báo "chưa đăng nhập" chứ không crash) → đóng gói theo từng kênh (dưới) → đẩy lên từng kênh (job `release` cần lại ma trận `windows-latest`/`ubuntu-latest` cho bước này, khác lát cắt Phase 13 chỉ chạy trên `ubuntu-latest`). - **PyInstaller dạng thư mục (`onedir`) nén zip/tar.gz, không dùng `onefile`**: `onefile` giải nén ra thư mục tạm mỗi lần chạy (chậm hơn 1–2 s) và bị antivirus báo nhầm nhiều hơn hẳn — quan trọng vì binary Windows **không ký**. - **Build trên đúng OS** (`cryptg` là extension biên dịch, không cross-compile được); Linux build trên runner Ubuntu cũ nhất còn hỗ trợ để binary chạy được trên glibc cũ. Chỉ Windows và Linux; macOS không làm (cần notarize). - **Chỗ PyInstaller hay gãy** cần test trong smoke test: backend của `keyring` được tìm qua entry point (cần `copy_metadata("keyring")`/hidden import), `hachoir` nạp parser động, `questionary`/`prompt_toolkit` trên console Windows, `platformdirs`. Từng kênh: - **PyPI bằng Trusted Publishing** (OIDC, không token trong repo; tự gắn attestation Sigstore). `uv tool install tgmirror` / `pipx install tgmirror` (Phase 7 đã xác nhận gói cài được) — rẻ nhất, cho người đã có Python. - **winget (Windows)**: zip `onedir` (`InstallerType: zip`, `NestedInstallerType: portable`) — chốt lại 2026-09-27, xem "Đã chốt" mục 6. **Không mua chứng chỉ ký (EV/OV)**: winget chấp nhận installer không ký; cái giá là cảnh báo SmartScreen lần chạy đầu. Rủi ro thật: pipeline kiểm duyệt của `winget-pkgs` quét bằng Defender — nếu bị báo nhầm, gửi mẫu cho Microsoft để gỡ (false-positive submission). Lần đầu nộp tay (`wingetcreate new`) để giữ package id; từ bản sau, dùng GitHub Action **`vedantmgoyal9/winget-releaser`** (chốt 2026-09-27, thay vì tự viết bước `wingetcreate update --submit`; tên tài khoản GitHub sửa lại 2026-09-28 — README/`action.yml` hiện ở `vedantmgoyal9`, không còn `vedantmgoyal2009` như ghi lúc chốt, không phải đổi quyết định) gắn vào `release.yml`, chạy sau khi GitHub Release được tạo — nó tự chạy `wingetcreate update` và mở PR vào `microsoft/winget-pkgs` bằng một PAT của tài khoản GitHub người dùng (repo secret `WINGET_PAT`, scope `public_repo`); duyệt có thể mất vài ngày. Scoop (bucket riêng, không kiểm duyệt) là phương án phụ nếu winget kẹt. - **APT + RPM tự host trên GitHub Pages, ký GPG (Linux)**: `nfpm` đóng chính bản PyInstaller Linux thành `.deb` và `.rpm` (không build lại); `reprepro`/`aptly` tạo metadata APT và ký `InRelease`, `createrepo_c` tạo metadata RPM và ký `repomd.xml`; đẩy lên một repo/nhánh `gh-pages` riêng, chỉ giữ N bản gần nhất để không phình. User: thêm key vào `/usr/share/keyrings/tgmirror.gpg`, nguồn với `signed-by=` (không dùng `apt-key`, đã deprecated), rồi `apt install tgmirror` / `dnf install tgmirror`; cập nhật bằng `apt upgrade`. Ước lượng khoảng 1,5–2 ngày. Phương án bớt việc: Cloudsmith (miễn phí cho OSS, họ host và ký) — khoảng 0,5 ngày nhưng phụ thuộc bên thứ ba. - **Key GPG**: subkey chỉ để ký, riêng cho tgmirror; primary key cất offline; subkey + passphrase trong GitHub Actions secrets; public key công bố trên trang kho, fingerprint trong README; có ngày hết hạn và lịch gia hạn (key hết hạn là `apt update` của user báo lỗi). - **AUR (`tgmirror-bin`)**: PKGBUILD trỏ tới tar.gz trên GitHub Release; không cần ký; khoảng 2 giờ; cập nhật version + checksum tự động được trong `release.yml`. - **Không làm**: kho chính thức Debian/Fedora (cần sponsor, và policy không chấp nhận Telethon ghim đúng một bản vì dùng API private), PPA/COPR (build từ source, PPA không có mạng lúc build nên phải đóng gói mọi dependency Python), Snap (cân nhắc lại nếu có nhu cầu; `platformdirs` trong snap trỏ về `$SNAP_USER_DATA` cần kiểm tra), Flathub (dành cho app GUI). - Hoàn thành khi: push một tag thử (ví dụ `v0.2.0rc1`, lên TestPyPI) ra đủ artifact; trên máy sạch, cài được bằng winget (Windows), `apt install` (Ubuntu), `dnf install` (Fedora), và mỗi cách chạy được `tgmirror login`. #### Phase 14 — ghi chú (lát cắt winget, 2026-09-28) Theo yêu cầu người dùng ("publish luôn lên winget"), làm trước phần winget của Phase 14 thay vì để lại nguyên cho sau, cùng lúc chuẩn bị Phase 16. Phạm vi **chỉ winget**: không đụng PyInstaller Linux, APT/RPM, AUR (không ai trong số đó cần cho winget, và cả ba đều cần thêm tài khoản/khóa GPG chưa có). - `pyinstaller.spec`/`scripts/pyinstaller_entry.py`/nhóm dependency `pyinstaller` trong `pyproject.toml` **đã có sẵn từ trước** (commit `5116095`, "Phase 14 (start): PyInstaller spec for the onedir build") nhưng chưa từng được ghi vào lộ trình hay build thử — khoảng trống tài liệu, không phải việc mới. **Build thật lần đầu tại máy hôm nay**: `uv sync --group pyinstaller` rồi `uv run pyinstaller pyinstaller.spec` ra đúng `dist/tgmirror/tgmirror.exe`, không lỗi hidden import (`keyring.backends.*`, `hachoir.parser.*`, `prompt_toolkit`) — cảnh báo duy nhất là `tzdata` (vô hại, không dùng). Smoke test `tgmirror.exe --version`/`--help`/`doctor` đều chạy đúng, không crash — **lưu ý**: máy này đã đăng nhập thật nên `doctor` chạm cả các đích Telegram thật (kiểm "vẫn đăng được") chứ không phải trạng thái "chưa đăng nhập" trống của một máy CI sạch; đã báo lại cho người dùng ngay khi phát hiện. - `release.yml` thêm job `pyinstaller-windows` (`needs: build`, chạy trên `windows-latest`: cài `uv sync --frozen --group pyinstaller`, build bằng spec trên, smoke test ba lệnh như trên, nén `dist/tgmirror` thành `tgmirror--windows-x64.zip` bằng `Compress-Archive`, tải lên artifact `pyinstaller-windows`). `github-release` giờ `needs: [build, pyinstaller-windows]` và tải thêm artifact `pyinstaller-windows` vào `dist/` trước khi tạo Release, nên `files: dist/*` tự đính kèm luôn zip. - **Tách làm hai commit theo yêu cầu người dùng, để tag `v0.1.1` không mang theo job `winget-release`**: commit thứ nhất (`a9f947f`, "Phase 16 prep + Phase 14 (winget slice, part 1)": bump version + job `pyinstaller-windows` ở trên, chưa có `winget-release`) là commit sẽ gắn tag `v0.1.1`; commit thứ hai (ngay sau, cùng ngày: thêm job `winget-release`, dùng `vedantmgoyal9/winget-releaser@main` với `identifier: tamvcspk.tgmirror`, `installers-regex: '\.zip$'` — khác mặc định của action là đuôi `.exe|.msi|.msix` vì gói của mình là zip — `token: secrets.WINGET_PAT`, `needs: [build, github-release]`, chỉ chạy khi không phải pre-release) đã lên `main` nhưng **trước khi** người dùng tự nộp tay `wingetcreate new` (giữ package id `tamvcspk.tgmirror`; action `winget-releaser` chỉ *update* một manifest đã có, không tạo mới được) và thêm secret `WINGET_PAT` — nên bước duy nhất của job vẫn gác bằng `if: env.WINGET_PAT != ''`, phòng trường hợp một tag sau (`v0.1.2`...) được đẩy trước khi hai việc thủ công đó xong. - Kiểm bằng YAML thuần (`yaml.safe_load`) cho `release.yml`: cú pháp hợp lệ, đồ thị `needs` đúng (`pyinstaller-windows`→`build`; `github-release`→`[build, pyinstaller-windows]`; `winget-release`→`[build, github-release]`). `pytest` toàn bộ vẫn xanh sau khi bump version (1726 passed, 3 skipped) — không có test nào chạm `release.yml`/PyInstaller (đúng như Phase 13: kiểm workflow không phải bằng `pytest`). - **Đã chạy thật trên GitHub Actions ngày 2026-09-28** (tag `v0.1.1`): job `pyinstaller-windows` build+zip thành công, `github-release` đính đúng zip vào 6 assets của Release — xem "Phase 16". Job `winget-release` **chưa chạy thật** lần nào (vẫn chờ secret `WINGET_PAT`, xem dưới). - **Nộp tay `wingetcreate new` đã làm cùng ngày 2026-09-28**, qua wizard tương tác của người dùng (Claude hướng dẫn từng trường qua chat, không tự chạy lệnh vì cần đăng nhập GitHub của người dùng): trỏ tới zip trên GitHub Release `v0.1.1`, `PackageIdentifier: tamvcspk.tgmirror`, `InstallerType: Zip`/`NestedInstallerType: Portable` (có phụ thuộc file khác trong zip — đúng vì PyInstaller `onedir` không tự chạy độc lập), `Architecture: X64`. Ba lỗi bị phát hiện và sửa trước khi nộp: `PackageLocale` wingetcreate tự đoán `vi-VN` nhưng toàn bộ mô tả manifest viết bằng tiếng Anh nên phải là `en-US`; `Tags` bị gộp thành một chuỗi `"telegram, cli, backup, mirror"` thay vì 4 tag riêng; mục `Documentations`/Wiki bị thêm nhầm (repo không có Wiki nào, chỉ README) — cả ba sửa trực tiếp trên PR qua "Files changed" → edit, không re-submit qua `wingetcreate` để tránh tạo PR trùng. - **PR [`microsoft/winget-pkgs#442694`](https://github.com/microsoft/winget-pkgs/pull/442694)**: pipeline Azure validation pass, auto-merge đã bật sẵn, nhưng **vẫn Open tới 2026-10-12** (xác nhận qua chính trang PR) — còn thiếu người dùng **ký CLA** (label `Needs-CLA`) và sau đó **một moderator duyệt tay**. Secret `WINGET_PAT` **chưa được thêm** (chờ PR merge, xác nhận package id tồn tại thật, mới có ý nghĩa để job `winget-release` cập nhật). Coi lát cắt winget là xong hẳn khi: PR #442694 merge, `winget install tamvcspk.tgmirror` cài được trên máy sạch, và secret `WINGET_PAT` đã thêm để bản `v0.1.2`+ tự cập nhật qua `winget-release`. ### Phase 15a — Màn hình TUI full-screen (menu) cho backup/restore (xong 2026-09-27) Thêm vào lộ trình ngày 2026-09-26 (xem nhật ký quyết định) để lấp khoảng trống Phase 11a/11b để lại: `tgmirror backup`/`restore` chỉ chạy được bằng gõ lệnh hoặc wizard riêng của chúng (`BackupFlow`/`RestoreFlow`), không có mục nào trong `ui/menu/` như "New clone"/"Continue" đã có cho `clone`/`run` — ghi ở Phase 11a là "**chưa có mục trong menu full-screen**", "**chưa phân tích/ETA**". - Thêm hai mục "Backup"/"Restore" vào màn hình chính (`ui/menu/screens/main_menu.py`), theo đúng khuôn "New clone"/"Continue" đã có: `screens/backup.py::backup_screen`/`screens/restore.py::restore_screen` lái nguyên `BackupFlow`/`RestoreFlow` của CLI cổ điển qua `MenuPrompter` (không cần sửa gì ở hai flow đó hay ở `MenuPrompter`: cả hai đã nhận `Prompter` qua constructor từ trước). - "Backup" bàn giao sang `BackupScreen` (`ui/menu/backup_screen.py`, mới) — nhân bản khuôn `RunScreen` cho `BackupWriter`/`Backup` thay vì dùng chung một lớp cha (đúng tinh thần `engine/backup.py` đã tự nhân bản vòng lặp điều khiển của `engine/runner.py` vì tiến độ của backup là kiểu `Backup`, không phải `Run`, không có `total_items`/ETA — **hết đúng từ 2026-09-28**, xem nhật ký quyết định: `Backup` giờ có `total_items`, và `BackupTuiReporter` dùng chung `bar`/`progress_line`/`floods_tail`/`TransferLines` với `TuiReporter` qua `ui/progress.py`). Câu hỏi để ngỏ ở lúc ghi ý định — "`BackupWriter` chỉ có báo tiến độ dòng chữ thường, chưa rõ có khớp thẳng giao diện `Reporter` mà `TuiReporter` cần hay phải thêm một lớp chuyển đổi" — trả lời là **phải thêm lớp chuyển đổi**: `BackupTuiReporter` (cùng file), một `engine.backup.Reporter` thuần (không có `Live` riêng, chỉ `render()` như `TuiReporter`), tái dùng nguyên các khoá dịch `backup.*`/`tui.*` đã có (từ 2026-09-28: cộng thêm một khoá mới, `backup.analyzed`). - "Restore" bàn giao thẳng sang `RunScreen` đã có (một restore vẫn là một `Run` bình thường) — nhưng `RunScreen` trước đó chưa từng nhận `reader_override`, nên phải thêm tham số đó (thread vào `Runner(...)`), đúng cách `cli/commands/run.py::execute` đã làm. - **Phát hiện phụ khi thêm tham số đó**: `ui/menu/screens/resume.py::ResumeScreen` ("Chạy tiếp"/"Thử lại tin lỗi") dựng `RunScreen` mà chưa bao giờ truyền `reader_override` — nghĩa là trước bản vá này, tiếp tục một cặp bắt nguồn từ `restore` qua menu full-screen sẽ đọc nhầm gateway sống thay vì thư mục backup (`cli/commands/run.py::reader_override_for`/`retry.py` đã xử lý đúng cho CLI cổ điển từ Phase 11b, nhưng chưa từng nối vào `ui/menu/`). Đã vá cùng lúc: `ResumeScreen._start` tính `reader_override_for(outcome.run.options.from_backup)` (đọc từ `RunOptions.from_backup` đã lưu trên `StartedRun`, không cần đổi chữ ký `_prepare()`). - **Phát hiện phụ thứ hai, người dùng chỉ ra sau bản đầu**: câu hỏi thư mục (`backup.pick_dir`/`restore.pick_dir`, `Prompter.path`) ở giao diện menu vẫn chỉ là một câu hỏi chữ thường — không có Tab gợi ý đường dẫn như wizard cổ điển (`QuestionaryPrompter` gọi `questionary.path`, tức `GreatUXPathCompleter` của `questionary` bọc `PathCompleter` của prompt_toolkit), vì khung vẽ tay của menu không có line editor để gắn bộ gợi ý đó vào. Bản vá đầu tự viết một bộ so khớp riêng (`os.scandir`, so khớp không phân biệt hoa/thường) — người dùng chỉ ra nó lệch với wizard cổ điển, nên đã đổi lại: `ui/menu/prompter.py::complete_path` giờ gọi **đúng cùng một** `GreatUXPathCompleter` (không viết bộ so khớp thứ hai), chỉ tự vẽ kết quả của nó (`Completion.text`/`display_text`) vào khung hand-drawn thay vì line editor của prompt_toolkit — nên giờ phân biệt hoa/thường giống hệt wizard cổ điển. Một phím Tab mới (`MenuKey.TAB`, `cli/keys.py::decode_menu_key` giải mã byte `\t`) khớp một mục thì hoàn thành luôn (dấu phân cách của thư mục đã có sẵn trong `Completion.text` của `GreatUXPathCompleter`, để Tab tiếp theo đi sâu vào trong), khớp nhiều mục thì hoàn thành tới phần chung dài nhất (`os.path.commonprefix` trên các `Completion.text`) và liệt các mục dưới ô nhập (gõ tiếp để lọc thêm); `MenuPrompter.path()` giờ dùng `PathQuestion` thay vì rơi về `TextQuestion`. Thêm khoá `menu.footer_path`. - Kiểm bằng `FakeGateway`/`Store` thật trong `tmp_path` (`tests/unit/test_backup_screen.py`, `tests/unit/test_menu_backup_restore.py`): backup/restore wizard hỏi đúng như CLI rồi bàn giao đúng màn hình; `q` dừng backup giữa chừng không thoát cả app; kết quả chỉ báo một lần; và một test hồi quy dựng thẳng một cặp restore bằng `begin_run`/`Runner(reader_override=...)` rồi "Chạy tiếp" qua `ResumeScreen`, xác nhận `RunScreen` nhận đúng lại `BackupReader`. `complete_path`/`PathQuestion` kiểm riêng trên thư mục thật trong `tmp_path` (`tests/unit/test_menu_prompter.py`): một mục khớp, nhiều mục khớp (hoàn thành phần chung, liệt ra), `only_directories` bỏ qua file, không khớp thì giữ nguyên, và phân biệt hoa/thường đúng như bộ so khớp của wizard cổ điển. - **Người dùng đã xác nhận trên terminal thật (2026-09-27)**: mục Backup/Restore trong menu full-screen chạy và hoạt động đúng. Chưa ghi lại chi tiết đã thử gì (một hay cả hai chiều, dừng/tiếp tục giữa chừng, Tab gợi ý đường dẫn) — bổ sung khi biết thêm. - Hoàn thành khi: gõ trơn `tgmirror` vào được màn hình chính, có mục Backup/Restore, chạy được, dừng/tiếp tục bằng phím giống `clone`/`run` — không cần gõ lệnh. ### Phase 15b — Hardening toàn dự án trước phát hành (xong: Đợt 1–3 2026-09-27, Đợt 4 2026-10-12) Thêm vào lộ trình ngày 2026-09-27 ngay sau Phase 15a. **Phạm vi đổi cùng ngày theo yêu cầu người dùng**: không chỉ diff của Phase 15a mà **toàn bộ dự án** — đây là lần hardening cuối trước khi phát hành (Phase 16). Tìm **bug**, **trùng lặp**, **code luộm thuộm/vô lý**, **kiến trúc chưa ổn**, **lệch tài liệu**; ghi lại phát hiện, giải pháp, kế hoạch; sửa theo kế hoạch ở các đợt sau (đợt review này không sửa code). **Cách review**: tự đọc lại toàn bộ `engine/`, `store/`, `core/` (gateway Telethon, pool, limiter, config, paths), `cli/` (run/restore/backup/errors/interrupt/keys), `ui/menu/` (app, run/backup screen, prompter, wizard, các screen 15a), `store/appdata.py`, CI/release/Dockerfile, README; chạy `pytest`/`ruff`; tái hiện bằng script những gì nghi là bug (ghi rõ bên dưới cái nào **đã tái hiện**, cái nào **cần xác minh**). **Mốc ban đầu**: `ruff check`/`ruff format --check` sạch. `pytest`: **3 test treo** (N1), 1644 test còn lại xanh. Đã kiểm và **ổn**: luật 1 có test kiến trúc giữ; 227 khoá thông điệp dùng trong code đều có trong `ui/messages.py`, VI/EN khớp khoá và tham số; `appdata import` chỉ đọc đúng các mục có tên (không có path traversal); log debug menu không ghi ký tự gõ; mặc định truyền file ở `05-chong-flood.md`/`02-cli-ux.md` khớp `core/config.py`. #### Phát hiện Mức: **N** = nghiêm trọng, chặn phát hành · **C** = cao · **T** = trung bình · **L** = thấp/dọn dẹp. | # | Phát hiện | Bằng chứng | Giải pháp đề xuất | |---|---|---|---| | N1 | **CI đang đỏ**: `tests/unit/test_cli_app_menu.py` — 3 test (`quits_from_the_main_menu`, `shows_whoami_on_the_account_screen`, `new_clone_opens_the_wizard...`) treo vì đếm số phím Down tới mục cần chọn, mà 15a chèn thêm "Backup"/"Restore". Trên Windows, pytest-timeout (kiểu thread) giết cả tiến trình khi một test quá giờ → mất kết quả cả job; `release.yml` cũng sẽ đỏ. | Đã tái hiện: chạy riêng từng test | Test chọn mục theo **giá trị/nhãn** (tìm vị trí mục trong `SelectList`), không đếm phím; thêm quy ước "chạy **toàn bộ** suite trước khi commit" vào skill `cli-wizard`. | | N2 | **Restore mất tin im lặng khi text có U+2028/U+2029/U+0085**: `backupdir.iter_records` tách dòng bằng `splitlines()` (tách cả các ký tự này), trong khi `json.dumps(ensure_ascii=False)` không escape chúng → dòng bị cắt đôi → JSON lỗi → `break` → mọi tin từ đó trở đi biến mất khi restore. `last_id` đọc theo `\n` nên backup vẫn tưởng đủ. | Đã tái hiện: 3 tin, tin đầu có U+2028 → `iter_records` trả **0 tin**, `last_id` = 3 | Đọc chỉ tách theo `\n` (và/hoặc ghi với escape ASCII). Backup cũ đọc lại được ngay nhờ sửa phía đọc, không cần làm lại. Test với các ký tự này. | | N3 | **Dòng dở cuối `messages.jsonl` không bao giờ bị cắt**: kế hoạch Phase 11 ghi "dòng cuối có thể dở (cắt bỏ khi mở lại)" nhưng code chỉ bỏ qua khi đọc. Lần backup kế tiếp **ghi nối vào đúng dòng dở** → dòng hỏng vĩnh viễn nằm giữa file → mỗi lần backup sau lại đọc `last_id` cũ, tải lại và ghi nối lại mãi; restore mất toàn bộ phần sau dòng hỏng. | Đã tái hiện: ghi 1,2 + dòng dở, rồi ghi tiếp 3,4 → `last_id` = 2, restore thấy [1, 2] | Khi mở một thư mục để backup tiếp: cắt file về sau dòng hoàn chỉnh cuối cùng (ghi tạm rồi thay thế nguyên tử, hoặc truncate). Dòng hỏng **giữa** file: báo lỗi rõ (không im lặng), kèm cách sửa. Test kill-giữa-dòng rồi chạy tiếp rồi restore. | | N4 | **Lần chạy/backup kẹt ở `running` khi lỗi không phải `TgMirrorError`**: `Runner.run`/`BackupWriter.run` chỉ `finish` với `TgMirrorError`/`Interrupted`; Ctrl+C lần hai (`KeyboardInterrupt`), `OSError` (đĩa đầy khi tải/ghi backup), `RuntimeError` (N5), `ValueError` (`results_of`/`copy_batch` lệch số) để lại dòng `running` với heartbeat mới → chạy lại trong 2 phút bị `RunBusy`/`BackupBusy` ("tiến trình khác đang giữ" dù đã chết). `cli/errors.run` chỉ bắt `TgMirrorError` → người dùng thấy traceback thô. | Đọc code (`engine/runner.py`, `engine/backup.py`, `cli/errors.py`) | Một nhánh bắt mọi lỗi còn lại ở `Runner`/`BackupWriter`: đóng dòng (`failed`, lý do `crashed: `, hoặc `interrupted` với Ctrl+C lần hai), ghi store được che khỏi hủy, rồi ném lại. `cli/errors.run`: một câu + gợi ý `--debug`, mã 1; `OSError` hết chỗ đĩa thành câu riêng. Reconcile vẫn lo phần batch dở như cũ. | | N5 | **Nguyên nhân khả dĩ của `RuntimeError` còn mở từ 2026-09-24** ("Nghi vấn nguyên nhân gốc" ở Phase 7): trong `engine/reupload.py::Pipeline._next`, khi producer kết thúc (đặt `_End`/`_Failure` như `Interrupted` sau `q`) **đúng lúc** getter bị hủy vì hết `poll_interval`, item vẫn nằm trong queue nhưng code kết luận "the download task ended early"/"was cancelled" → `RuntimeError` thay cho dừng êm, và dẫn tới N4. Khớp triệu chứng đã ghi (sau `q` vài giây, status vẫn `running`). | Suy luận từ code + ngữ nghĩa `asyncio.Queue.get` khi bị hủy; **chưa tái hiện** bằng test | Trước khi kết luận producer chết: lấy nốt item còn trong queue (không chờ). Viết test tất định dựng đúng thứ tự "producer xong + getter bị hủy cùng lượt". Sau đó gỡ chú thích "temporary" ở `ui/menu/run_screen.py::_drive` (giữ log debug như người dùng đã chọn). | | N6 | **Cặp restore mà thư mục backup đã mất/đổi chỗ** (kể cả sau `appdata import` sang máy khác): `begin_run` thấy `backup.json` không còn thì lặng lẽ rơi về kiểm nguồn sống, **tạo dòng run**, rồi `cli/commands/run.py::reader_override_for` gặp `assert` → crash; ở menu, `ResumeScreen._start` gọi nó ngoài `try` → sập cả app; dòng run kẹt `running` (N4). Docstring `store/appdata.py` khẳng định "không bảng nào giữ đường dẫn tuyệt đối" — sai từ Phase 11 (`backups.dir`, `RunOptions.from_backup`). | Đọc code | Kiểm thư mục **trước** khi tạo dòng run; cho người dùng chọn **cập nhật đường dẫn** (thư mục mới cùng nguồn, delta tiếp) hoặc **chạy lại từ đầu** (theo trả lời của người dùng, chi tiết ở Đợt 1). Sửa docstring appdata và ghi hạn chế này ở Phase 10/11. | | N7 | **Hai tiến trình dùng chung session**: khóa SQLite của session Telethon chỉ lộ khi *ghi*, nên tiến trình thứ hai (ví dụ `backup` ở terminal này, `clone` ở terminal kia) mở được bình thường rồi giữa chừng chết vì `sqlite3.OperationalError: database is locked` sau ~5 giây — không được ánh xạ thành `SessionBusy`, ra traceback, run kẹt (N4). "Một tiến trình mỗi session" (skill `telethon-engine`) chỉ được giữ ở lúc kết nối. | Đã tái hiện với hai `SQLiteSession` trên cùng file | Khóa độc quyền cấp hệ điều hành trên một file khóa cạnh session, lấy trong `telethon_session` và giữ tới khi ngắt: tiến trình thứ hai báo `SessionBusy` ngay lúc mở. Ánh xạ thêm "database is locked" giữa chừng thành `SessionBusy`. (Lệnh không kết nối như `pause`/`stop`/`status`/`history` không bị ảnh hưởng.) | | C1 | `tgmirror restore --force-takeover` **không có tác dụng**: `RestoreOptions.force_takeover` không bao giờ được truyền vào `RunRequest.force`. | Đọc code | Truyền vào `RestoreFlow.ready()`; test. | | C2 | **Backup mất tên file gốc**: file lưu thành `media/`, `ExportedMedia` không giữ tên gốc → restore gửi tài liệu tên `12345.pdf` thay vì tên thật (cũng mất tiêu đề/ca sĩ của audio). | Đọc code (`TelethonGateway.export_unit`, `_send_backup_one`) | Thêm trường tùy chọn tên gốc (và title/performer audio) vào dòng `messages.jsonl` — tương thích ngược (bản cũ bỏ qua trường lạ, `FORMAT_VERSION` giữ 1); restore gửi kèm tên đó. Cần người dùng đồng ý (đổi định dạng đã chốt ở "Đã chốt" mục 3, dù chỉ là thêm). | | C3 | **Menu: thông báo và tiến độ file của run bị in thẳng ra màn hình**: `RunScreen` dùng `TuiReporter` mà `notice`/`transfer` in qua console toàn cục (`LineReporter`) — trong alt-screen của menu, dòng đó vẽ đè từ góc trên rồi bị lần vẽ kế tiếp xoá → nháy hình, và tiến độ tải lên/xuống file lớn (thông tin chính khi reupload 2 GB) gần như không thấy được trong menu. | Đọc code Rich `Live.process_renderables`; **cần xác minh trên terminal thật** | Cho `TuiReporter` một chế độ không in: giữ vài thông báo gần nhất và dòng file đang truyền **trong** `render()`; menu dùng chế độ đó, CLI cổ điển giữ như cũ. | | T1 | Backup **không hiện ở đâu**: `history`, `status`, menu "Lịch sử"/"Trạng thái" và badge "đang chạy ở nơi khác" chỉ xem `runs`; `appdata export` chỉ chặn khi có run đang chạy, không xét backup. (Khoảng trống đã ghi từ Phase 11a.) | Đọc code | Thêm backup vào `history` (CLI + menu) và badge; `appdata export` chặn cả khi backup đang chạy. Cần người dùng chọn làm trước hay sau 0.1.1. | | T2 | **Reconcile luôn gửi trùng placeholder**: batch pending là game/invoice gửi dưới dạng placeholder text; so khớp dạng tin (game ≠ text) → `AMBIGUOUS` → gửi lại → trùng. | Đọc `engine/reconcile.py` | Khi so khớp, coi unit có hành động placeholder là tin text. | | T3 | Menu backup/restore, chi tiết UX: (a) thư mục đang chứa backup của nguồn khác → wizard kết thúc thay vì hỏi lại thư mục (`_check_existing` là bước riêng không hỏi gì); (b) `~` không được mở rộng trong `cli/wizard.py::_ask_dir` → tạo thư mục tên `~` trong thư mục hiện tại; (c) `complete_path` quét đĩa đồng bộ trên event loop (đường dẫn mạng có thể treo khung). | Đọc code | (a) gộp kiểm vào bước hỏi thư mục để `run_steps` hỏi lại; (b) mở rộng `~`; (c) chạy quét trong thread. | | T4 | CI/phát hành: không test trên Python 3.11 (bản tối thiểu, cũng là bản trong Docker) — CI dùng Python mặc định của runner; `Dockerfile` chép `uv:latest` (không ghim); action ghim theo tag; `contents: write` cấp cho cả job cầm secret Docker Hub; thứ tự đẩy Docker Hub → GitHub Release → PyPI nên PyPI lỗi là phát hành dở. | Đọc workflow | Ma trận Python 3.11 + mới nhất; ghim `uv` theo phiên bản; quyền tối thiểu theo job; cân nhắc đẩy PyPI trước ảnh `:latest` (hoặc chấp nhận và ghi lại cách chạy lại). | | T5 | `sessions/` chỉ được đặt quyền 0700 khi **mới tạo**; thư mục có sẵn với quyền rộng hơn không được siết. | Đọc `core/paths.py` | Siết quyền cả khi thư mục đã có (POSIX). | | L1 | **Câu hỏi kiến trúc của 15a — `BackupScreen` vs `RunScreen`**: hai lớp trùng ~80% (tạo task, `stop_on_interrupt`, `p`/`r`/`q`, `tick` báo kết quả một lần, thoát 130). Phần trùng là *điều khiển giao diện*, không phụ thuộc `Run`/`Backup`. Kết luận: **nên gộp** phần đó vào một lớp màn hình chạy-tác-vụ chung; giữ riêng engine (`Runner`/`BackupWriter`) và reporter như hiện tại. | Đọc code | Lớp chung + hai lớp con chỉ cung cấp tác vụ, reporter, dòng mở đầu/kết quả. | | L2 | Dòng mở đầu/kết quả viết hai nơi: `cli/commands/run.py::execute` và `ui/menu/run_screen.py::_start_lines/_result_lines`; tương tự backup (`cli/commands/backup.py::execute` và `ui/menu/backup_screen.py::_result_lines`). Số tin `gone` của backup không hiện ở cả hai. | Đọc code | Hàm thuần trả danh sách dòng, CLI và menu dùng chung; thêm `gone`. | | L3 | Hằng lặp: `EXIT_INTERRUPTED` ×4, `ADMIN_ACK_FLAG` ở nhiều lệnh, `PAIR_CHOICES` ×2. | grep | Một chỗ định nghĩa. | | L4 | Hiển thị trùng: đầu panel `BackupTuiReporter` lặp đúng dòng "Lần backup …" đã in; dòng phím `tui.keys` vừa trong panel vừa ở footer (cả `RunScreen`). | Đọc code | Bỏ bản lặp. | | L5 | Vặt: `RunScreen.tick` đọc thuộc tính riêng `_reporter._run`; `pump_menu_keys` giải mã phím hai lần; `begin_backup` dùng `utc_now()` bỏ qua clock tiêm vào; `src_about` luôn rỗng và không có `avatar.jpg` như kế hoạch Phase 11 ghi. | Đọc code | Sửa vặt; với `about`/`avatar`: sửa tài liệu cho khớp (không làm tính năng mới). | | L6 | Tài liệu lệch: README ghi Phase 15 chưa bắt đầu và danh sách menu thiếu Backup/Restore (**đã sửa cùng đợt review này**); `CLAUDE.md` Layout thiếu `ui/menu/backup_screen.py`; docstring `store/appdata.py` (N6). | Đọc | Sửa cùng các đợt dưới. | #### Người dùng trả lời (2026-09-27) 1. **Làm cả Đợt 1 lẫn Đợt 2 rồi mới phát hành** (mọi mục T1–T5, không bỏ mục nào); Đợt 3 (dọn dẹp) và Đợt 4 (xác minh) cũng theo kế hoạch, trước Phase 16. 2. C2: **đồng ý** thêm trường tên file gốc (tùy chọn, tương thích ngược) vào `messages.jsonl` — ghi vào "Đã chốt" mục 8. 3. N7: **đồng ý** chặn hẳn hai lệnh kết nối Telegram chạy song song trên cùng session (kể cả `backup` + `clone`). 4. N6: cặp restore mất thư mục thì người dùng được chọn **chạy lại từ đầu** hoặc **cập nhật đường dẫn thư mục** của cặp (không chỉ một câu lỗi) — thiết kế ở mục N6 của Đợt 1 dưới đây. #### Kế hoạch thực hiện (sẵn sàng bắt đầu ở phiên sau) Quy tắc chung cho mọi phiên của 15b: - Mỗi phiên làm trọn một hoặc vài mục theo đúng thứ tự dưới; mỗi mục có **test hồi quy tái hiện đúng kịch bản** ở cột "Bằng chứng" (test đỏ trước khi sửa, xanh sau khi sửa). - Kết thúc phiên: toàn bộ `pytest` (không chỉ file mới — chính lỗi này sinh ra N1) + `ruff check` + `ruff format --check`, rồi doc-sync; đánh dấu mục đã xong ngay trong danh sách dưới (`[x]` + ngày). - Lệnh trên máy Windows này: `.venv/Scripts/python.exe -m pytest` (không dùng `uv run` trong công cụ Bash). - Mục chạm vòng runner/backup/checkpoint (N3, N4, N5, N6): đọc skill `checkpoint-state` và `flood-safety` trước; mục chạm Telethon (N7, C2): skill `telethon-engine`; mục chạm CLI/menu: skill `cli-wizard`. **Đợt 1 — chặn phát hành** - [x] **N1 — CI xanh lại** (2026-09-27, làm đầu tiên). `tests/unit/test_cli_app_menu.py`: ba test treo (đã tái hiện: `--timeout=15` treo, `--timeout=-100` là ngoại lệ pytest thật) đã đếm phím Down cố định, trong khi 15a thêm "Backup"/"Restore" đẩy mọi mục sau xuống. Thêm hàm trợ giúp `down_presses_to(app_, action)`: dựng một `MainMenuScreen` dùng thử, `await on_enter()`, tìm vị trí của `action` trong `_list.items`, trả đúng số `MenuKey.DOWN`. Ba test đổi sang gọi hàm này thay vì `range(6)`/`range(4)` cố định. Đã rà `grep "MenuKey.DOWN"` toàn `tests/`: các chỗ khác (`test_menu_wizard.py`) đếm trong danh sách của từng bước wizard, không phải `MainMenuScreen`, không bị ảnh hưởng. Thêm quy ước vào skill `cli-wizard` ("Testing a list-driven screen", "Run the full suite before committing"). Toàn bộ `pytest` (1649 test) + `ruff check`/`format --check` xanh. - [x] **N2 + N3 — `messages.jsonl` bền** (2026-09-27; ô này quên tick lúc làm, đánh dấu 2026-10-12 sau khi kiểm `engine/backupdir.py`: `CorruptMessagesFile`, `repair_trailing_line`, chỉ tách theo ` `) (`engine/backupdir.py`). (a) Đọc chỉ tách theo `\n` ở mọi chỗ đọc (`iter_records`, `last_id`) và ghi sao cho không còn ký tự ngắt dòng Unicode trần trong một dòng. (b) Hàm "sửa đuôi file" gọi khi `begin_backup` mở một thư mục đã có: cắt bỏ phần sau ký tự `\n` cuối cùng nếu dòng cuối không phải JSON hợp lệ (thay thế nguyên tử hoặc truncate, không bao giờ xoá dòng hợp lệ). (c) Dòng hỏng **ở giữa** file: `iter_records` không im lặng dừng nữa mà ném một lỗi riêng (thuộc `BackupError`, có câu trong `ui/messages.py`) nêu số dòng — restore và backup tiếp đều từ chối cho tới khi người dùng xử lý. Test: U+2028/U+2029/U+0085 trong text, tên file, poll; kill giữa dòng → backup tiếp → restore đủ tin; dòng hỏng giữa file → lỗi rõ. - [x] **N4 — không còn run/backup kẹt `running`** (2026-09-27). `Runner.run` và `BackupWriter.run`: thêm nhánh `except BaseException` cuối (sau các nhánh cụ thể có sẵn): đóng dòng `failed` với lý do `interrupted` (`KeyboardInterrupt`/`CancelledError` — Ctrl+C lần hai) hoặc `crashed: : `, lệnh ghi store che khỏi hủy bằng `asyncio.shield` (+ `contextlib.suppress(CancelledError)` quanh chính lệnh ghi đó), rồi ném lại nguyên lỗi; batch đang `pending` giữ nguyên để reconcile như cũ (không đổi). `cli/errors.py`: thêm `describe_any(exc)` (dùng chung bởi `run()` và menu) — `TgMirrorError` như cũ, `OSError` với `errno.ENOSPC` thành `err.disk_full`, `OSError` khác thành `err.os_error`, còn lại thành `err.crashed` (gợi ý `--debug`); `run()` thêm nhánh `except OSError`/`except Exception` cuối cùng, **nhưng trước đó phải chặn riêng `except typer.Exit: raise`** — một `typer.Exit` (Ctrl+C lần một ở `run.py`/`backup.py::execute`, mã 130) cũng là `Exception`, nên nếu không chặn trước, nhánh bắt-tất-cả mới thêm sẽ nuốt nó thành mã 1 (bắt được nhờ chạy toàn bộ suite, không chỉ file mới: `test_ctrl_c_saves_and_exits_130_then_run_finishes_without_duplicates` đỏ). `RunScreen`/`BackupScreen` (`ui/menu/`) dùng `describe_any` thay `describe(...) if isinstance(exc, TgMirrorError) else str(exc)`, nên giờ hiện đúng câu CLI hiện cho cùng lỗi. Test: `tests/integration/test_runner.py::test_crash_closes_the_run_failed_instead_of_leaving_it_running`, `tests/integration/test_backup.py::test_crash_closes_the_backup_failed_instead_of_leaving_it_running` (gateway giả ném `RuntimeError` giữa batch → dòng `failed`, chạy lại ngay không cần `--force-takeover`, không trùng/sót), `tests/unit/test_cli_errors.py` (mọi nhánh của `describe_any`/`run()`, kể cả `--debug` và OS error thường), `tests/unit/test_run_screen.py`/`test_backup_screen.py` (`describe_any` hiện trong `_lines`). - [x] **N5 — race `Pipeline._next`** (2026-09-27, `engine/reupload.py`). Trước khi kết luận "producer chết sớm": kiểm `queue.empty()`, còn thì `queue.get_nowait()` lấy nốt item thay vì ném `RuntimeError`. Test tất định `tests/unit/test_reupload.py::test_next_recovers_an_item_the_poll_timeout_raced_the_producer_for` (stub `asyncio.wait` dựng đúng thứ tự đua, không dựa thời gian thật; xác nhận đỏ trước khi sửa). Đã gỡ chú thích "temporary" ở `ui/menu/run_screen.py::_drive` (giữ log debug) và đóng mục "việc còn mở" ở "Kế hoạch giao diện full-screen (menu)" — xem ghi chú ở đó. - [x] **N6 — cặp restore mất thư mục: chạy lại từ đầu hoặc cập nhật đường dẫn** (2026-09-27, theo trả lời 4). - Phát hiện sớm: `begin_run` (`engine/runs.py`) ném `BackupDirMissing` (mới, kế `RunError`) ngay khi `request.from_backup` có mà `backupdir.read_manifest` trả `None` — **trước** khi tạo dòng run; cùng chỗ, `manifest.src_id != src.id` ném `WrongBackupSource`. `reader_override_for` (`cli/commands/run.py`) không còn `assert`, ném `BackupDirMissing` thay (chỉ còn trúng ở khoảng hở cực hẹp giữa hai lời gọi). `begin_run` không bao giờ lặng lẽ rơi về kiểm nguồn sống cho một restore. - **Cập nhật đường dẫn**: thêm `--from-backup DIR` cho `tgmirror run`/`retry` (`resume_flow`/`retry_flow_for` nhận tham số mới, đè `target.options.from_backup`) để trỏ cặp restore sang thư mục mới mà không qua wizard restore — `begin_run` tự kiểm `src_id` khớp, từ chối rõ nếu khác nguồn. Menu: `ResumeScreen._start` bắt `BackupDirMissing`, đẩy một `WizardScreen` hỏi "Chọn thư mục backup khác / Chạy lại từ đầu / Huỷ" (thư mục mới dùng `MenuPrompter.path`) thay vì để lỗi lan lên. - **Chạy lại từ đầu**: thêm `--fresh` cho `tgmirror restore` (`RestoreOptions.fresh`, bước `RestoreFlow._confirm_fresh` tái dùng `run.py::confirm_fresh` — giống `clone --fresh`: quên tiến độ của cặp, hỏi xác nhận, `--yes` đồng ý). Menu dùng cùng đường qua `_prepare(fresh=True)`. - Sửa docstring `store/appdata.py` (đường dẫn tuyệt đối có trong `backups.dir`, `RunOptions.from_backup`) và ghi hạn chế "sang máy khác phải trỏ lại thư mục backup" ở ghi chú Phase 10/11 và `02-cli-ux.md`. - Test: `tests/integration/test_restore.py` (xoá thư mục → không tạo dòng run; nguồn khác bị từ chối; trỏ lại thư mục mới tiếp đúng delta), `tests/unit/test_cli_restore.py` (như trên qua CLI thật: `run`, `run --from-backup`, `restore --fresh`), `tests/unit/test_menu_backup_restore.py` (menu không sập: nhánh Huỷ và nhánh chọn thư mục mới). - [x] **N7 — một tiến trình mỗi session** (2026-09-27). Thêm `core/session_lock.py::session_lock` (thuần OS, không import Telethon): khóa độc quyền không chờ trên một file cạnh file session (`fcntl.flock` POSIX, `msvcrt.locking` Windows, đã kiểm trên máy Windows thật), tự nhả khi tiến trình đóng file hoặc chết (kể cả bị kill, không cần dọn dẹp như `RunBusy`/`BackupBusy` dựa heartbeat). `core/telethon_gateway.py::telethon_session` lấy khóa này **trước khi** `make_client`/`connect()`, giữ tới khi ngắt; không lấy được → `SessionBusy` ngay, trước cả khi mở session SQLite (khoá SQLite của session chỉ lộ khi *ghi*, nên không có khoá này thì tiến trình thứ hai `connect()` thành công rồi mới chết muộn giữa chừng). `map_exception` thêm ánh xạ `sqlite3.OperationalError` chứa "locked" thành `SessionBusy` (lớp phòng vệ thứ hai cho phần hở còn lại — ví dụ tiến trình khác không phải tgmirror). Lệnh chỉ đọc store (`pause`/`stop`/`status`/`history`) không bao giờ gọi `telethon_session` nên không bao giờ lấy khóa — không cần sửa gì thêm. Ghi thành luật cứng số 10 trong `CLAUDE.md` và cập nhật skill `telethon-engine`. Test: `tests/unit/test_session_lock.py` (khóa/nhả/lỗi vẫn nhả, hai đường dẫn khác nhau không đụng nhau), `tests/unit/test_telethon_gateway.py::test_telethon_session_refuses_a_second_open_on_the_same_session` (client giả qua `monkeypatch`, xác nhận đỏ trước khi có khóa — hai `SQLiteSession` cùng file không tự đụng nhau lúc connect, đúng như báo cáo), cùng file thêm test cho `map_exception`'s ánh xạ mới (và một test âm: `OperationalError` không chứa "locked" thì không bị ánh xạ nhầm). - [x] **C1 — `restore --force-takeover`** (2026-09-27): truyền `force=self._o.force_takeover` vào `RunRequest` trong `RestoreFlow.ready()`. Test: `tests/unit/test_cli_restore.py::test_restore_force_takeover_actually_forces_a_takeover` (giữ cặp bằng một run "sống" giả, restore lại bị từ chối `RunBusy`, restore lại với `--force-takeover` thì qua). **Đợt 2 — độ tin cậy/UX** (người dùng chốt làm hết trước phát hành) - [x] **C2 — giữ tên file gốc** (2026-09-27): thêm `original_filename`/`audio_title`/`audio_performer` vào `ExportedMedia` (`core/gateway.py`) — `backupdir.py`'s cơ chế `asdict`/`fields()` sẵn có đã tổng quát nên tự động ghi/đọc/bỏ qua khi thiếu, không cần sửa gì thêm ở đó. `export_unit` (`telethon_gateway.py`) điền từ `message.file.name`/`.title`/`.performer` (thuộc tính có sẵn của Telethon, `None` khi không áp dụng). Restore: `_backup_attributes()` (mới) dựng `DocumentAttributeFilename`/`DocumentAttributeAudio` từ các trường này — `None` thì không thêm gì, hành vi y hệt trước (dựa vào tự nhận diện của Telegram/hachoir); `_send_backup_one` truyền qua `send_file(attributes=...)`, `_backup_album_member` truyền qua `_upload_album_member(attributes=...)` (trước đây không truyền gì, luôn mất tên trên đường album). `FORMAT_VERSION` giữ 1. Test: `tests/unit/test_backupdir.py` (round-trip, dòng cũ thiếu trường vẫn đọc được), `tests/unit/test_telethon_restore.py` (tên file gốc và tiêu đề/người trình bày audio tới đúng `send_file`/`UploadMediaRequest`, backup không có trường mới thì không gửi `attributes` thừa). - [x] **C3 — menu hiện thông báo/tiến độ file trong khung** (2026-09-27, sửa code — **còn cần người dùng kiểm trên terminal thật**, xem Đợt 4). `TuiReporter` (`ui/tui.py`) thêm tham số `silent: bool = False`: khi bật, `notice()`/`transfer()` (qua `LineReporter` dùng chung) không còn gọi `self._live.console.print` (nguyên nhân vẽ đè/nháy hình trong menu, vì `RunScreen` không bao giờ mở `TuiReporter` như context manager) mà đẩy vào một hàng đợi nội bộ (`_buffer`, tối đa `RECENT_LINES=5`), `render()` in ra ngay trong khung. `RunScreen` giờ dựng `TuiReporter(limits, current, silent=True)`; CLI cổ điển (`cli/runtime.py`) không đổi, vẫn in trên `Live` riêng như cũ (đúng ý định). Test: `tests/unit/test_tui.py` (`silent=True` không in gì ra console, thông báo hiện trong `render()`, chỉ giữ vài dòng gần nhất, `silent=False` vẫn in như cũ và không lặp vào panel) — xác nhận đỏ trước khi sửa. - [x] **T1 — backup hiện ở mọi nơi xem nhật ký** (2026-09-27). `store.active_backup()`/`list_backups()` đã có sẵn từ Phase 11a, chỉ chưa được dùng ở đây. `cli/commands/history.py`: gộp `list_runs`+`list_backups` (hai dãy id độc lập, hai bảng riêng — gộp và sắp theo `started_at` ở Python, không SQL UNION), mã hàng đổi thành `R`/`B` (một cột "Loại" riêng làm bảng vỡ dòng ở 80 cột — phát hiện bằng test đỏ thật, không đoán). `ui/menu/screens/history.py`: `HistoryScreen` liệt cả hai kiểu, chọn một backup ra `BackupHistoryDetailScreen` (mới, tóm tắt gọn — không có tin lỗi/flood để tra như `HistoryDetailScreen`). `engine/status.py`: thêm `BackupStatusReport`/`build_backup_report` (không có fraction/ETA, giống `BackupTuiReporter` — Phase 11a chưa phân tích tổng số); `store/floodlog.py`/`db.py` thêm `events_of_backup`/`backup_flood_events` (cột `backup_id` đã có sẵn trong `flood_log`, chỉ chưa có hàm đọc). `cli/commands/status.py`/`ui/menu/screens/status_dashboard.py`: chọn lần chạy sống, rồi backup sống, rồi cái mới hơn giữa hai "gần nhất" (một tài khoản, một session — N7 đảm bảo tối đa một trong hai đang sống cùng lúc). Badge `ui/menu/app.py::_refresh_badge` xét cả `active_backup`; `Screen.backup_id`/`MenuApp.own_backup_id` (mới, giống `run_id`/`own_run_id`) để badge bỏ qua backup chính app đang chạy. `store/appdata.py::export_appdata` thêm kiểm `active_backup()`. Cập nhật `02-cli-ux.md` (bảng lệnh, mục "Backup ra đĩa", phần menu). Test: `tests/unit/test_cli_run.py`/`test_cli_retry.py` (history/status liệt/hiện backup qua CLI, JSON có `"kind"`), `tests/unit/test_menu_badge.py` (badge cho backup, ẩn cho backup của chính app), `tests/unit/test_appdata.py` (export từ chối khi backup đang sống), `tests/unit/test_menu_backup_restore.py` (menu "Lịch sử" liệt cả hai, Enter đúng màn hình chi tiết theo loại). - [x] **T2 — reconcile placeholder** (2026-09-27): `engine/reconcile.py::judge`/`_shape` nhận thêm `placeholders: Collection[int]` (id nguồn nào được coi là `MediaKind.TEXT` thay vì kind thật khi so hình dạng). `engine/runner.py::_reconcile` tính tập đó bằng `_placeholder_ids` (mới) — gọi lại `plan_unit` cho từng tin `pending` có kind poll/game/invoice, an toàn không bao giờ ném `UnsupportedMedia` vì một tin đã tới được `pending` nghĩa là `plan_unit` đã từng thành công với đúng `run.options` này (bất biến trong một lần chạy). Test: `tests/unit/test_reconcile.py` (hàm `judge` thuần: placeholder khớp đúng kind thật ở tail, không có gợi ý thì vẫn sai như trước, gợi ý sai id không che lấp một khác biệt thật), `tests/integration/test_runner_reupload.py::test_killed_after_a_placeholder_the_next_run_reconciles_it_not_resends_it` (giết giữa lúc gửi placeholder, chạy lại → `reconciled`, không gửi trùng — xác nhận đỏ trước khi sửa). - [x] **T3 — UX thư mục** (2026-09-27). (a) `cli/commands/backup.py::BackupFlow`: gộp `_check_existing` vào `_pick_dir` (không còn là bước riêng trong `steps()`), thử lại tối đa `wizard.MAX_TITLE_ATTEMPTS` lần khi `WrongSource` (thư mục đã chứa backup nguồn khác) — nhưng **không** thử lại khi `RunWaiting` (thư mục còn chờ FloodWait): đổi thư mục không trả lời được câu hỏi "thư mục này chưa dùng được ngay", nên vẫn thoát thẳng như cũ (đã kiểm bằng một test cũ đỏ khi thử lại cả hai). (b) `cli/wizard.py`: tách `resolve_dir_answer` (mới, `strip()` + `expanduser()` + `resolve()`) khỏi `_ask_dir`, dùng chung cho cả `ask_backup_dir`/`ask_restore_dir` và màn hình khôi phục thư mục backup của menu (`ui/menu/screens/resume.py`, vốn tự gọi `prompter.path` riêng, chưa từng qua `_ask_dir` nên cũng thiếu `~`). (c) `ui/menu/prompter.py::MenuPrompter.handle_key` đổi thành `async def`, phím Tab của một `PathQuestion` chạy `complete_path` qua `asyncio.to_thread` thay vì gọi thẳng (đồng bộ, có thể treo cả khung nếu đường dẫn là ổ mạng) — mọi phím khác vẫn gọi thẳng `question.handle_key` như cũ. `ui/menu/screens/wizard.py::WizardScreen.handle_key` và mọi chỗ gọi `prompter.handle_key` (kể cả test) thêm `await`. Test: `tests/unit/test_cli_backup.py` (wizard hỏi lại đúng thư mục khi trước đó chọn nhầm, không thoát), `tests/unit/test_wizard.py` (mới — `resolve_dir_answer`/`ask_backup_dir` mở rộng `~`), `tests/unit/test_menu_prompter.py` (Tab chạy off-loop: một task chạy song song phải kịp tiến trong lúc quét — không chỉ sau khi quét xong) — cả ba xác nhận đỏ trước khi sửa. - [x] **T4 — CI/phát hành** (2026-09-27; xem "Phase 13 — ghi chú" mục sửa T4 để biết chi tiết và những gì đã tự tay xác nhận bằng Docker/YAML thật trên máy): ma trận Python 3.11 + 3.14 trên cả hai OS (`ci.yml` — **xác nhận xanh trên GitHub Actions thật 2026-09-27**, xem Đợt 4 dưới); ghim `ghcr.io/astral-sh/uv:0.8.13` trong `Dockerfile` (đã `docker build` thật, không chỉ đoán); `release.yml` tách 1 job thành 5, mỗi job chỉ xin quyền nó cần, và `:latest` chỉ gắn (`docker buildx imagetools create`, không build lại) sau khi GitHub Release + PyPI đã xong — cách chạy lại khi một job fail: chỉ chạy lại job đó (và job phụ thuộc), ghi ngay đầu `release.yml`. `release.yml` bản thân nó **vẫn chưa chạy trên GitHub Actions thật** (chỉ kích hoạt bởi tag `v*`), để dành Phase 16. - [x] **T5 — quyền `sessions/`** (2026-09-27). `core/paths.py::Paths.ensure()`: `mkdir(mode=0o700, exist_ok=True)` chỉ áp `mode` lúc **tạo mới** — thư mục có sẵn với quyền rộng hơn không được đổi, nên thêm `sessions_dir.chmod(0o700)` riêng (chỉ POSIX, `os.name != "nt"`: trên Windows `chmod` không có ý nghĩa bit-cho-bit giống POSIX, `stat()` sau `chmod` luôn trả `0o777` bất kể — đã tự tay xác nhận trên máy Windows, không đoán). `cli/commands/doctor.py`: thêm `_permission_lines` — đọc `sessions_dir`'s mode hiện tại, cảnh báo nếu rộng hơn `0o700`; gọi **trước** mọi thứ khác trong `command()` (kể cả `rt.connect`/`opened_store`, đều tự gọi `Paths.ensure()`), nếu không lệnh tự siết lại trước khi kịp đọc, cảnh báo không bao giờ hiện. Test (POSIX-only, `pytest.mark.skipif(os.name == "nt", ...)` — máy dev là Windows nên tự tay xác nhận `os.chmod`/`stat` không phản ánh đúng bit trên Windows thay vì đoán): `tests/unit/test_paths.py::test_ensure_tightens_an_already_existing_sessions_dir`, `tests/unit/test_cli_doctor.py::test_reports_session_directory_permissions_ok`/`test_warns_about_a_widened_session_directory`. **Đợt 3 — dọn dẹp** (không đổi hành vi; test hiện có phải xanh nguyên) — **xong 2026-09-27** - [x] **L1** (2026-09-27) `ui/menu/task_screen.py::TaskScreen[T]` (generic theo kết quả `Run`/`Backup`): giữ `stop_on_interrupt`, `RunControl`, `_lines`/`_task`/`_reported`/`_interrupt_hit`, `render`/`handle_key`/`tick` chung; ba chỗ khác nhau (`_run`, `self._reporter`, `_result_lines`) là những gì lớp con cung cấp. `RunScreen` override thêm `on_enter`/`handle_key`/`tick` chỉ để thêm dòng `debug.log` (giữ nguyên như trước, không có ở `BackupScreen`) rồi gọi `super()`. Test hiện có (`test_run_screen.py`, `test_backup_screen.py`, `test_menu_backup_restore.py`, `test_menu_badge.py`) xanh nguyên không cần sửa. - [x] **L2** (2026-09-27) `ui/lines.py` (mới): `run_start_lines`/`run_result_lines`/`backup_start_line`/`backup_result_lines` — hàm thuần, dùng chung bởi `cli/commands/run.py`/`backup.py::execute` (echo từng dòng) và `RunScreen`/`BackupScreen` (nối vào `_lines`). Lời tuyên bố D3 ("full responsibility") **không** nằm trong hàm dùng chung: CLI in nó ra stderr (cảnh báo, không phải tiến độ), menu không có stream riêng để tách — mỗi nơi tự in/nối dòng đó trước khi gọi hàm chung, y hệt trước. Thêm dòng `gone` cho kết quả backup (`retry.gone`, tái dùng khoá đã có) — trước đây `Backup.gone` không hiện ở CLI lẫn menu. - [x] **L3** (2026-09-27) `EXIT_INTERRUPTED` chỉ còn định nghĩa ở `cli/errors.py`, nơi khác import; `ADMIN_ACK_FLAG`/`PAIR_CHOICES` chỉ còn định nghĩa ở `cli/wizard.py` (đã là nơi giữ `MAX_TITLE_ATTEMPTS` tương tự), `clone.py`/`backup.py`/`restore.py`/`run.py`/`resume.py` dùng `wizard.ADMIN_ACK_FLAG`/`wizard.PAIR_CHOICES`. - [x] **L4** (2026-09-27) `BackupTuiReporter.render()` không còn in lại dòng "Lần backup …" (đã có ở `BackupScreen._lines`, một lần); `TuiReporter.render()` chỉ in dòng phím `tui.keys` khi **không** `silent` (CLI cổ điển không có footer riêng, giữ nguyên); `BackupTuiReporter.render()` bỏ hẳn dòng đó (menu luôn có footer, không bao giờ dùng ngoài menu). - [x] **L5** (2026-09-27) `TuiReporter` thêm property `run` công khai, `RunScreen.tick` dùng `self._reporter.run` thay `self._reporter._run`; `pump_menu_keys` dùng lại biến `decoded` đã giải mã thay vì gọi `decode_menu_key(raw)` lần hai; `begin_backup` (`engine/backup.py`) thêm tham số `clock: Clock = utc_now` (giống `begin_run`), dùng `clock()` thay `utc_now()` trực tiếp cho `check_runnable`. Tài liệu Phase 11a/11b ("Khác với kế hoạch ở trên") đã ghi đúng thực tế `src_about` luôn `""` và không có `avatar.jpg` từ trước — không cần sửa thêm. - [x] **L6** (2026-09-27) `CLAUDE.md` Layout: thêm `ui/lines.py` và `ui/menu/task_screen.py` vào mục `ui/`. README đã đúng (Backup/Restore có trong danh sách menu từ đợt review); không cần sửa thêm. **Đợt 4 — xác minh** (phần lớn do người dùng làm) - [x] `scripts/mutation_check.py` — mẫu cập nhật cho cơ chế mới của Đợt 1/2 (2026-09-27): thêm 8 mutation (sửa đuôi JSONL/ký tự ngắt dòng Unicode N2, dòng hỏng giữa file N3, khóa session N7, ánh xạ `database is locked` N7, nhánh bắt lỗi còn lại của run/backup N4, `except typer.Exit` bị nhánh bắt-tất-cả nuốt mất N4) và các file/test-node liên quan vào `TESTS`; nhân tiện phát hiện và sửa 6 mẫu cũ lệch theo code đã đổi từ trước (D3 x2, `batcher.py`, caption append, album `force_document`, placeholder) — đã xác nhận cả 60 mẫu khớp đúng 1 lần trong mã nguồn. Đã tự chạy toàn bộ script (không chỉ `--list`): **60/60 caught, không mẫu nào SKIPPED hay SURVIVED**. - [x] **Người dùng xác nhận xong 2026-10-12.** Thử thật: restore một backup thật sang kênh mới (Phase 11b chưa từng thử live: thứ tự, album, topic, tên file gốc); dừng/tiếp backup và restore trong menu; kill giữa lúc backup rồi chạy tiếp rồi restore đủ tin; mở hai terminal cùng lúc (lần hai phải báo `SessionBusy` ngay); đổi chỗ thư mục backup rồi dùng cả hai đường "cập nhật đường dẫn"/"chạy lại từ đầu". - [x] CI (`ci.yml`) xanh trên cả hai OS và cả hai bản Python (2026-09-27): `gh run view` xác nhận cả 4 job (`ubuntu-latest`/`windows-latest` × Python 3.11/3.14) xanh trên GitHub Actions thật, cho cả commit Đợt 1+2 (`36326508515`) lẫn Đợt 3 (`36328472853`). `release.yml` (kích hoạt bằng tag `v*`) vẫn để dành Phase 16 — không phải mục này. - Hoàn thành khi: mọi ô trong bốn đợt trên đã tick (hoặc người dùng chấp nhận để lại, ghi rõ lý do), CI xanh, và người dùng xác nhận phần thử thật của Đợt 4. ### Phase 16 — Phát hành 0.1.1 chính thức (xong 2026-09-28) Thêm vào lộ trình ngày 2026-09-27 (xem nhật ký quyết định), tách riêng khỏi Phase 14: đóng tiêu chí bỏ ngỏ của Phase 13 — "chưa thử với một tag thật" — bằng cách thật sự bấm phát hành, không phải thêm code mới. - Bump `version` trong `pyproject.toml` từ `0.1.0` lên `0.1.1` (commit `a9f947f`), tạo tag `v0.1.1`, push tag để kích hoạt `release.yml` — **người dùng đã tự bấm phát hành thật ngày 2026-09-28**. - **Trục trặc lần đầu, đã sửa cùng ngày**: job `publish-pypi` fail với `invalid-publisher` vì Trusted Publisher trên pypi.org (owner `tamvcspk`, repo `tgmirror`, workflow `release.yml`, environment `pypi`) **chưa được tạo trước khi push tag** — token OIDC gửi lên không khớp publisher nào. Người dùng tạo "pending publisher" đúng 3 trường trên tại `pypi.org/manage/account/publishing/`, rồi bấm "Re-run failed jobs" trên GitHub Actions (không tag/push lại) — `publish-pypi` chạy lại thành công, lần publish đó tự biến pending publisher thành publisher chính thức; `docker-latest` (đang chờ `publish-pypi`) chạy theo sau đó. - Đã xác nhận cả bốn job chạy đúng trên GitHub Actions thật, kiểm lại trực tiếp qua PyPI/Docker Hub/GitHub ngày 2026-10-12 (không chỉ dựa lời người dùng): PyPI có `tgmirror-0.1.1-py3-none-any.whl`/`.tar.gz`; Docker Hub `tamvo1808/tgmirror` có cả tag `0.1.1` và `latest` cùng digest; GitHub Release `v0.1.1` đánh dấu Latest, 6 assets kèm `SHA256SUMS` và zip PyInstaller Windows (Phase 14). - Hoàn thành khi: tag `v0.1.1` lên đúng GitHub Release kèm `SHA256SUMS`, ảnh lên `docker.io/tamvo1808/tgmirror:0.1.1`, gói lên `pypi.org/project/tgmirror/0.1.1`. **Đạt cả ba.** ### Phase 18a — ghi chú (xong 2026-10-12; đã thử trên Telegram thật một phần, xem dưới) Chi tiết thiết kế đã chuyển sang `01-kien-truc.md` ("Khám phá"), `02-cli-ux.md` ("Khám phá nguồn"), `03-filters.md` ("Selection" và các predicate mới); `07-inspect-transform.md` giữ phần lý do và những gì chưa làm (Phase 18b/19/20). **Đã làm** (ngoài các mục đã nêu ở 07 mục 3–4 và 8): - `SrcMessage`/`ExportedMessage`/`messages.jsonl` mang metadata mới (forward, reply, edit, domain link, tên/khóa file, forwards, reactions, ...); predicate `forwarded`, `forwarded_from`, `is_reply`, `edited`, `link`, `filename`, `forwards`, `reactions`; cờ `--forwarded/--not-forwarded`, `--forwarded-from`, `--has-link`, `--link-domain`. - `tgmirror inspect` (`engine/inspect.py`, `cli/commands/inspect.py`): báo cáo trên kênh sống (qua `FloodGuard`) hoặc thư mục backup (offline), `--by` 10 bảng, `--list`, `--json`, `--csv`, `--plan` (pre-flight, `engine/preflight.py`), `--save`/`--freeze`, `@last`, "dùng tiếp với đúng filter này". - File selection (`engine/selection.py`), `--selection`/`--exact` cho `clone`/`backup`/`restore` (`cli/selection_options.py`), lựa chọn "dùng kết quả khám phá gần nhất" trong bước filter của wizard (dùng chung cho dòng lệnh và menu vì cùng `*Flow`). **Khác với đề xuất ở `07`** (không đụng D1–D10): 1. **`--has-link [DOMAIN]` thành hai cờ** `--has-link` và `--link-domain DOMAIN`: giá trị tùy chọn của một cờ không có cách an toàn qua Typer/Click. 2. **`link` không đẩy xuống server** (07 mục 3.3 đề xuất `InputMessagesFilterUrl`): chưa biết filter đó có bỏ sót tin có text-URL/link trong caption không, mà luật pushdown là "không chắc thì không đẩy". Thêm vào spike dưới. 3. **`--exact` cài bằng predicate `message_ids` của filter**, không phải "đọc theo id như retry" (07 mục 4.4): không đổi `Runner`, delta/resume/`filters_json` chạy như một filter bình thường, và cận id vẫn thu hẹp khoảng đọc. Cái giá: khoảng đọc là từ id nhỏ nhất đến lớn nhất của danh sách, không phải từng id; một danh sách rất thưa trên kênh lớn vẫn đọc cả khoảng. 4. **`@last` luôn kèm danh sách id** (07 chỉ nói `--freeze` mới có `snapshot`): để `--selection @last --exact` chạy được. Một file `--save` thường chỉ có snapshot khi `--freeze`. Chỉ ghi `@last` khi quét **xong**. 5. **`inspect` đọc cả nguồn** dù có filter (không pushdown): báo cáo mô tả cả nguồn lẫn phần được chọn, nên phải thấy hết. Rẻ hơn khi có chỉ mục (18b). 6. **`--by duplicate`** thêm theo 07 mục 3.1 ("Trùng lặp"), dựa trên `file_key`; **`--csv`** ghi UTF-8 có BOM (Excel + tiếng Việt). 7. **Pre-flight chỉ nói sàn thời gian theo limiter** (không ước tốc độ truyền: phụ thuộc đường mạng và chưa có số liệu đáng tin); kiểm giới hạn dung lượng upload (spike 13) vẫn chưa làm — chỉ nói file lớn nhất. 8. **`FloodOwner.of_inspect`**: một lần quét không có dòng `runs`/`backups`, nên `flood_log` để trống cả `run_id` và `backup_id` (không cần cột mới). 9. **Chưa có** mục "Inspect"/màn hình "Khám phá" trong menu full-screen (Phase 18b); lựa chọn "dùng kết quả gần nhất" thì đã có trong menu vì dùng chung wizard. **Kết quả kiểm trên Telegram thật (người dùng, 2026-10-12)**: `reply_to_id` trong forum **đúng**; `fwd_from` có thông tin (cột `forwarded_from`); tổng `reactions` **chính xác**; quét một kênh ~13.000 tin mất **2 phút 22 giây** (~1,1 s/trang cách nhau `READ_WAIT` = 1 s) nên 100.000 tin ≈ 18 phút. `--by duplicate` **chạy đúng** (người dùng xác nhận sau khi thử với hai bản trong cùng nguồn), tức `file_key` giữ nguyên qua forward. Lần đầu không thấy bảng vì chưa truyền `--by duplicate` (mặc định chỉ `media month hashtag`); đã thêm cột `file_key` vào CSV/JSON để soi từng tin. **Chưa kiểm** (chạy `tgmirror inspect` trên một kênh/forum thật rồi đối chiếu với Telegram Desktop): - `forwards`/`views` có trong nguồn group không. - `InputMessagesFilterUrl` có thu hẹp an toàn cho predicate `link` không (nếu có thì đẩy xuống server). - Quét thật một kênh ~100.000 tin (mới đo 13.000 tin; ngoại suy tuyến tính ~18 phút, chưa có FloodWait nào ở cỡ đó). - Hành vi đã xác nhận (người dùng, 2026-10-12): `reply_to_id` trong forum, `fwd_from` (cột `forwarded_from`), `file_key` qua forward (`--by duplicate`), tổng `reactions`, thời gian quét 13.000 tin; `file_name`: **ảnh không có tên file, GIF và sticker có** (nên `filename: "*.jpg"` không bao giờ khớp ảnh). **Test mới** (1992 pass, 3 skip lúc ghi): `test_links.py`, `test_filter_metadata.py`, `test_inspect.py`, `test_preflight.py`, `test_selection.py`, `test_cli_inspect.py` (có "plan khớp lần clone thật" và "clone `@last` sao chép đúng số tin inspect đã báo", tức tiêu chí hoàn thành của 18a trên `FakeGateway`), bổ sung vào `test_telethon_messages.py`, `test_backupdir.py`, `test_backup_reader.py`, `test_architecture.py` và `tests/integration/test_pushdown_equivalence.py` (predicate mới + `message_ids` cùng predicate đẩy xuống được). ### Phase 19 — ghi chú (bắt đầu 2026-10-13; lát 19a xong code và đã thử trên Telegram thật cùng ngày; 19b và 19b1 xong code cùng ngày, forum → forum đã thử thật; 19c1 xong code và đã thử thật 2026-10-14; 19c2 xong code cùng ngày) **Chia lát cắt** (như 11a/11b, 18a/18b; không đổi D1–D10): `07` mục 5 gồm sáu việc độc lập nhau về đường code, nên làm theo thứ tự phụ thuộc, mỗi lát cắt là một lần commit chạy được: - **19a — mô hình Transform + thao tác caption** (xong code): nền mà hai lát sau cùng dùng (`engine/transform.py`, `RunOptions.transform_json`, `--transform`, selection mang `transform:`). Không thêm hành vi Telegram mới ngoài viết lại caption phong phú hơn. - **19b — định tuyến** (xong code, xem "Đã làm ở 19b"): hashtag → topic (`auto`/`map`/`default`/`strip`), `topic_map`, chọn định dạng hashtag của topic → hashtag. Đây là tiêu chí hoàn thành của cả Phase 19 ("clone kênh thường sang forum: đúng topic, đúng thứ tự trong từng topic"). - **19b1 — cờ cho phần còn lại của `topics`** (xong code, xem "Đã làm ở 19b1"): `--topic-map`, `--topic-default`, `--strip-routing-hashtag`; không thêm hành vi mới, chỉ thêm đường cờ cho những gì file đã làm được. - **19c — tham chiếu**, chia tiếp theo thứ tự phụ thuộc (mỗi lát một commit chạy được): - **19c1 — giữ reply** (xong code, đã thử thật, xem "Đã làm ở 19c1"): `reply: keep` / `--keep-replies`, qua `msg_map`. - **19c2 — `forward_header: keep`** (xong code, xem "Đã làm ở 19c2"): forward giữ "Forwarded from" (`drop_author` tắt); `scripts/spike_forward_header.py` cho câu hỏi spike 5 chưa kiểm. - **19c3 — link nội bộ lùi** (xong code, xem "Đã làm ở 19c3"): `links: rewrite`, `t.me//` → tin tương ứng ở đích qua `msg_map`. **Đã làm ở 19a**: - `core/gateway.py`: `StripLinks`/`RemoveHashtags`/`RemoveMentions`/`Replace`/`Append`/`Clear`, `ops_of_mode` (cờ `--caption` → danh sách), `CaptionPolicy.ops`/`text_too`/`all_ops`/`rewrites`. - `core/telethon_gateway.py`: `rewrite_caption` chạy từng thao tác theo thứ tự; `_apply_edits` thay `strip_source_links` làm nơi duy nhất dịch entity (hàm cũ giữ tên, cùng kết quả: các test cũ không đổi); `_plain_text` cho `text_too` ở cả đường gửi sống và đường restore từ backup. - `engine/transform.py` (pure), `cli/transform_options.py` (`--transform` dùng chung `clone`/`restore`/`inspect --plan`), `engine/selection.py` đọc/ghi `transform:`, `engine/strategy.py` (`router`/`may_reupload` nhận `transform=`), `engine/runs.py` (`RunRequest.transform_json`, ba luật loại trừ trong `check_options`), `engine/preflight.py`, `run`/`retry` mang theo `transform_json` của cặp. - Test mới: `test_transform.py` (model, 16 ca từ chối, từng thao tác với entity UTF-16), `integration/test_runner_transform.py` (đường đi theo unit, `text_too`, D3, nhớ theo cặp), `test_cli_transform.py` (clone, `run`, selection, `backup` từ chối, pre-flight), một ca restore trong `test_cli_restore.py`; `tests/fakes.py` áp các thao tác lên chữ thuần (xấp xỉ theo từ, đủ cho test tầng runner; bản thật được test với entity ở `test_transform.py`). **Khác với đề xuất ở `07` mục 5.2** (không đụng D1–D10): 1. **`clear: true` thay cho `--caption none`** trong danh sách (07 không đặt tên thao tác này); `text_too` giữ đúng vị trí là một mục của danh sách như 07 đề xuất, nhưng chỉ được một lần và không phải thao tác (`Transform.text_too`). 2. **`strip_links: source` không tự bỏ `@nguồn`**: `--caption strip-links` là `strip_links: source` **cộng** `remove_mentions: source` (`ops_of_mode`); đúng hành vi cũ, mỗi thao tác đơn lẻ làm một việc. 3. **`replace.with` là chữ nguyên văn**, không có tham chiếu nhóm (`\1`): 07 không nói, và một mẫu thay có nhóm sai chỉ lộ lúc chạy. 4. **Chỉ `remove_hashtags` dọn khoảng trắng** quanh chỗ bị cắt (`"a #b c"` → `"a c"`); `strip_links`/`remove_mentions` giữ hành vi cũ của `--caption strip-links` (`"a b"` hai dấu cách), vì test và tài liệu hiện có đã ghi như vậy. 5. **Không ghép `--caption` với `--transform`** (hai cách viết cùng một danh sách theo thứ tự không ai viết ra là một sự đoán): lỗi mã 2. 6. **Router không biết thao tác có đổi gì không**: unit có caption đi đường gửi lại dù không thao tác nào khớp (cùng cách `--caption append` hôm nay). Pre-flight đếm đúng như vậy. 7. **Không có bước wizard cho transform**: chỉ qua `--transform` / `transform:` trong selection (luật 7 đủ: cờ là tập cha của wizard). Wizard "nạp từ file" từ chối file selection mang transform và chỉ sang `--selection`, thay vì dùng filter mà âm thầm bỏ transform. 8. **Chưa làm** (còn lại của 07 mục 5.4 cho lát này): cảnh báo "đổi transform giữa chừng, tin đã chép không bị sửa lại" khi clone lại một cặp có transform khác — hiện chỉ ghi trong `02-cli-ux.md`; `scripts/mutation_check.py` chưa có mẫu cho cơ chế mới (người dùng chạy tay, mục nhớ về lệnh dev trên máy này). **Kiểm trên Telegram thật (người dùng, 2026-10-13)**: đã chạy theo kịch bản gồm pre-flight `inspect --plan --transform`, `clone --transform` sang kênh mới (hashtag, `replace`, `append`, định dạng quanh vùng bị đổi, album), `text_too`, nguồn `noforwards` với lời tuyên bố D3, `restore --transform` từ backup thật và `run` dùng lại transform đã nhớ — **toàn bộ pass**, không có sai lệch nào cần sửa. (Người dùng báo kết quả chung, không ghi từng bước; chưa ghi số liệu riêng.) **Đã làm ở 19b**: - `engine/transform.py`: `Transform.topics: TopicRules` (`routes` theo thứ tự ưu tiên, `auto_all`/`auto_limit`/`auto_skip`, `default`, `strip`, `renames`, `hashtag_format`), `is_empty`/`rewrites`/`routes_to_topics`; khóa `topics` hết bị đặt trước, còn `reply`/`forward_header`/`links` cho 19c. Dạng chuẩn JSON dùng danh sách mục một khóa (thứ tự là ưu tiên, `sort_keys` không phá) và `{id|title, to}` cho `topic_map` (JSON không giữ id là số khi làm khóa). - `engine/batcher.py` (`Batch.dst_topic`, `topic_of=`), `engine/runner.py` (truyền `transform.topics.destination`, `strip=` khi gửi), `engine/topics.py` (`TopicResolver.resolve(src_topic_id, dst_title)`; tìm topic đích theo tên trước khi tạo), `engine/reupload.py` (`strip=`, `_caption_of`), `engine/strategy.py` (`router`/`may_reupload` dùng `Transform.rewrites`; `strip` chỉ đẩy đúng unit có hashtag đã định tuyến sang gửi lại). - `engine/endpoints.py` (`plan_endpoints(forum=...)`, `Plan.forum`, `DestinationNotForum`), `engine/runs.py` (`check_options` và kiểm đích trong `begin_run`), `cli/commands/clone.py`/`restore.py` (truyền `forum=`), `cli/errors.py`, `ui/messages.py`. - `engine/preflight.py` + `ui/tables.py`: `Plan.topics` (unit theo topic đích) và số lần forward tính theo từng đoạn cùng nơi đến (trước đây `ceil(unit / batch)` bỏ qua việc topic đổi thì batch cắt). - Test mới: `tests/integration/test_runner_topic_rules.py` (định tuyến, thứ tự trong topic, album, `default`, topic có sẵn dùng lại, `strip` với/không `text_too`, `topic_map` gộp, hashtag thay topic, đích không phải forum), phần `topics` trong `tests/unit/test_transform.py`, `tests/unit/test_cli_transform.py` (đích mới là forum, đích thường bị từ chối, `run` tiếp, pre-flight), `tests/unit/test_preflight.py`, một ca restore trong `tests/unit/test_cli_restore.py`, một ca khứ hồi file selection trong `tests/unit/test_selection.py`; `auto: all` (giới hạn, `skip`, kết hợp `map`, `strip`) ở `test_runner_topic_rules.py`/`test_transform.py` và cờ `--hashtag-to-topic` ở `test_cli_transform.py`. Cả bộ: 2119 pass, 3 skip (trước 19b: 2049). **Khác với đề xuất ở `07` mục 5.1/5.4** (không đụng D1–D10): 1. **Cờ tắt chỉ có `--hashtag-to-topic`** (= `auto: all`); không có `--topic-map` và không có bước wizard: phần còn lại qua `--transform` / `transform:` trong selection, như 19a (luật 7: cờ là tập cha của wizard). *(Ba cờ còn lại thêm ở 19b1, ngay dưới; wizard vẫn không có.)* 2. **`auto: all` thay cho "top N từ inspect"**: không quét cả nguồn để đếm (hàng nghìn lời gọi đọc không nên ẩn sau một khóa); thay vào đó mọi hashtag tự thành topic khi gặp, và một **giới hạn an toàn** (`limit`, mặc định 30 topic mới mỗi lần chạy, quá thì vào General kèm thông báo) chặn việc tạo hàng trăm topic ngoài ý muốn. Bản đầu của 19b chỉ có `auto: [danh sách]` và bắt liệt kê từng hashtag; người dùng phản hồi cùng ngày rằng phải tự động được, nên thêm `auto: all`. Mỗi tin chỉ vào **một** topic: hashtag đầu tiên viết trong tin (rule `map` thắng nếu có). 3. **`default` chỉ cho tin không nằm trong topic nguồn nào**: forum nguồn → forum đích, tin trong topic "Tin tức" không có hashtag nào khớp vẫn về topic ánh xạ của nó, không bị gom vào `default`. 4. **`topic_map` không có `drop`** (07 đề xuất): bỏ một topic là việc của filter `exclude: topic` — một cách duy nhất, và tin bị bỏ vẫn được đếm đúng ở `skipped_filter`. 5. **Topic đích tìm theo tên, không thêm bảng**: không migration (`topic_map` giữ nguyên là id nguồn → id đích). Đổi nhỏ ở đường Phase 8: topic đích trùng tên được dùng lại thay vì tạo thêm; mất `topic_map` (hay crash giữa `create_topic` và lưu) không còn tạo topic trùng. Đánh đổi: user đổi tên topic ở đích giữa hai lần chạy thì lần sau tạo lại topic tên cũ. 6. **`topic_map` cũng đặt tên hashtag** khi đích không phải forum (cùng với `hashtag_format`), nên không có lỗi "topic_map cần đích forum"; chỉ `hashtag_to_topic` buộc đích là forum. 7. **Transform không chọn tin; chọn là việc của filter** (người dùng chốt 2026-10-13, sau khi thấy một danh sách hashtag "danh sách trắng" nằm trong transform là bộ lọc thứ hai làm `inspect` đếm sai, phá `--exact`, mất pushdown và không quét lại khi đổi): một danh sách `map`/`auto` chỉ nói tin đi đâu, tin còn lại vẫn clone (vào `default` hay General); muốn chỉ lấy vài hashtag thì `--hashtag`. `topic_map` chỉ đổi tên, chọn topic bằng `--topic`. 8. **Cờ chồng lên file** (cùng quyết định): file là nền, cờ thêm/thay/làm hẹp theo từng loại trường (`03-filters.md`, "Cờ chồng lên file"; `02-cli-ux.md`, "Transform"). Đảo quyết định "không ghép" của 19a và `FilterMix`. `--caption` chạy **sau** các thao tác của file (`CaptionPolicy.all_ops` đổi thứ tự: trước 19b là cờ trước, nhưng hai thứ không đi cùng nhau được nên không lệnh cũ nào đổi nghĩa). Chỉ làm hẹp: hai danh sách "bất kỳ trong" của cùng một predicate không AND được trong một rule, nên cờ thay giá trị của file cho predicate đó (đã nói với người dùng). 9. **Phase 19b1** (người dùng chốt tách 2026-10-13, xong code cùng ngày): cờ cho phần còn lại của `topics` — `--topic-map "Cũ=Mới"`, `--topic-default TÊN`, `--strip-routing-hashtag` — theo cùng phép ghép; xem "Đã làm ở 19b1". 10. **`--mode copy` vẫn dùng được với định tuyến một mình** (forward vào topic); chỉ `strip` cần gửi lại. **Đã làm ở 19b1** (cùng ngày; không đụng D1–D10, không migration, không thêm lời gọi Telegram): - `engine/transform.py`: `TopicRules.layered(renames=, default=, strip=)` — thuần, một chỗ duy nhất định nghĩa "cờ chồng lên file" cho `topics`: giá trị đơn thay (`default`), công tắc chỉ bật (`strip`), `renames` thêm vào `topic_map` của file và thắng khi cùng một topic (dùng lại `_renames` nên cùng luật với file: topic 1, trùng khóa, tên rỗng/hai dòng/quá 128 ký tự). `default`/`strip` mà không có định tuyến (không `routes`, không `auto_all`) là `TransformError`, không bị lờ đi (cùng tinh thần với `limit`/`skip` không có `auto: all`). - `cli/transform_options.py`: `TopicMapOption`/`TopicDefaultOption`/`StripRoutingHashtagOption`, `TopicFlags` (gom bốn cờ `topics` thành một giá trị để lệnh chuyển tiếp) + `topic_flags(...)`, `with_topic_flags`; `resolve(..., topics=TopicFlags)` thay cho `hashtag_to_topic=`. `clone`, `restore`, `inspect` khai báo cả ba cờ mới. - Test mới: bốn ca trong `tests/unit/test_transform.py` (ghép, `strip` chỉ bật, năm ca bị từ chối, kiểm `default` như file), bốn nhóm trong `tests/unit/test_cli_transform.py` (cờ một mình không cần file, `--topic-map` theo tên/id không chọn tin, cờ thắng file cho cùng một topic, tám ca bị từ chối trước khi tạo gì). Cả bộ: 2138 pass, 3 skip (trước 19b1: 2119). **Chọn lựa ở 19b1** (người dùng không phải quyết, nêu để sửa nếu không hợp): 1. **`--topic-map` tách ở dấu `=` đầu tiên; vế trái toàn chữ số là id**, còn lại là tên. Một topic nguồn tên chỉ gồm chữ số hay có `=` thì viết trong file (`topic_map` cho phép khóa là chuỗi). Không thêm cú pháp `title:`/`id:` cho cờ chỉ vì ca hiếm đó. 2. **Chưa có cờ** cho `limit`/`skip` của `auto: all` và `hashtag_format`: `limit` mặc định 30 đủ cho ca thường và hai thứ kia là tinh chỉnh; thêm khi có người cần. Cũng **không có `--no-strip`**: file là nền, cờ chỉ thêm. 3. **Không có bước wizard** (đã nói ở 19a mục 7 và 19b mục 1); "top N hashtag đếm từ nguồn" (nhắc ở `02`) bị `auto: all` + `limit` thay hẳn, không còn là việc chờ. **Sửa sau lần thử đầu (2026-10-13, forum → forum với `t.yaml`)**: file chỉ có `topics:` / `hashtag_to_topic:` (khóa để trống) được đọc thành transform rỗng **không báo lỗi**, nên clone chạy như không có transform và hashtag không thành topic — trái với lời hứa của 19b là file sai thì mã 2. Sửa hai chỗ: một khóa của `topics` có mặt mà để trống là `TransformError` kèm gợi ý cần điền gì (`TopicRules.from_data`), và `--transform FILE` mà file không đổi gì là lỗi mã 2 (`cli/transform_options.py::_load`; `topics:`/`caption:` trống ở mức trên cùng vẫn hợp lệ khi đi trong selection). Đường forum → forum bản thân đúng (thêm `test_a_forum_source_routes_by_hashtag_into_topics_of_a_new_forum`: hashtag thắng topic nguồn, tin không hashtag giữ topic nguồn). Cả bộ: 2146 pass, 3 skip. **Kiểm trên Telegram thật (người dùng, 2026-10-13)**: forum → forum bằng file `--transform` (sau lần sửa ở trên) **chạy được**: hashtag thành topic ở đích. Người dùng báo ngắn gọn, không ghi từng bước hay số liệu; các cờ `--topic-map`/`--topic-default`/`--strip-routing-hashtag` chưa nghe báo riêng. **Còn chưa kiểm trên Telegram thật** (người dùng chạy; cùng câu hỏi mở số 9 ở "Việc cần xác minh sớm"): `ForwardMessagesRequest(top_msg_id=...)` và `reply_to=` có đưa tin vào đúng topic không khi nguồn **không phải** forum; một album forward vào topic có giữ nhóm không; tên `General` của topic 1 theo ngôn ngữ giao diện của tài khoản (nếu bản địa hóa thì `General` trong file không khớp, tin vào topic mới tên "General"); `create_topic` của một kênh broadcast vừa chuyển thành forum (`--dst-new` từ nguồn kênh thường). **Đã làm ở 19c1** (2026-10-14; không đụng D1–D10, không migration, không thêm bảng): - `engine/transform.py`: `Transform.keep_replies` (khóa `reply: keep|drop`, mặc định `drop`; `reply` hết bị đặt trước, còn `forward_header`/`links`), `rewrites_content` tách khỏi `rewrites` (`rewrites` thêm `keep_replies`: là thứ buộc tin phải gửi lại nên D3 và `--mode copy` xử như mọi biến đổi khác; `text_too` chỉ xét theo `rewrites_content`). - `core/gateway.py`: `Unit.reply_to_id`; `reply_to=` thêm vào `send_prepared`/`send_by_reference`/`send_text` (id **ở đích** của tin được trả lời). `core/telethon_gateway.py`: `_reply_of(topic, reply_to)` (Telethon chỉ nhận một id `reply_to`: reply thay chỗ topic); album qua `SendMultiMediaRequest` gửi cả `reply_to_msg_id` lẫn `top_msg_id`. - `engine/strategy.py`: `answers_something`/`KEEP_FORWARDING`; `router`/`may_reupload` gửi lại unit có reply. - `store/msgmap.py` + `Store.dst_id_of`; `engine/runner.py::_reply_target` giải reply (qua `msg_map` của **cặp**, nên bản sao do lần chạy trước tạo ra cũng tính) và đếm `reply_lost` vào `stats_json` (`Run.reply_lost`, dòng kết quả `run.reply_lost`). - `cli/transform_options.py`: `--keep-replies` trên `clone`/`restore`/`inspect --plan`, ghép như các cờ `topics`; `scripts/spike_reply.py` cho câu hỏi chưa kiểm được. - Test mới: `tests/integration/test_runner_replies.py` (10 ca: reply theo bản sao, lần chạy sau, tin được trả lời bị lọc/lỗi, media + album theo mã file, poll vẫn forward, D3, `--mode copy`, định tuyến hashtag không giữ reply qua topic), ca router/model/CLI/restore trong `test_reupload.py`, `test_transform.py`, `test_cli_transform.py`, `test_cli_restore.py`. **Khác với đề xuất ở `07` mục 5.1** (nêu để sửa nếu không hợp): 1. **Router không biết trước tin được trả lời có bản sao hay không** (là chuyện của `msg_map`, mà router thuần và đồng bộ): mọi unit có reply đều bị gửi lại, kể cả khi sau đó reply bị bỏ vì tin gốc nằm ngoài selection — cùng kiểu với ghi chú 19a mục 6. Pre-flight đếm đúng như vậy; tin bị bỏ reply nằm trong `reply_lost` của lần chạy. 2. **Poll, game, invoice và loại không rõ vẫn được forward** (reply mất, không đếm vào `reply_lost` vì không đi đường gửi lại): gửi lại poll làm mất phiếu, còn ba loại kia không có bản để gửi. 3. **Có định tuyến hashtag, reply chỉ giữ khi hai tin vào cùng một topic đích**: `msg_map` không lưu topic đích, nên runner đọc lại tin được trả lời (một lời gọi đọc qua `FloodGuard`) và so `TopicRules.destination` của hai bên. Một tin thuộc album mà hashtag nằm ở tin anh em thì so ra khác → bỏ reply (thận trọng, không đoán). Không có định tuyến thì không đọc thêm gì: reply trong forum luôn nằm cùng topic nguồn. 4. **Reply tới chỗ không còn bản sao** (tin gốc bị filter loại, `failed`, đã `gone`) → gửi tin **không kèm reply** và đếm; không bao giờ làm lỗi tin. 5. **Restore dùng cùng đường**: `reply_to_id` đọc từ `messages.jsonl`, bản sao tìm trong `msg_map` của chính lần restore. **Kiểm trên Telegram thật (người dùng chạy `scripts/spike_reply.py` trên một forum thử, 2026-10-14)**: tin gửi bằng `reply_to=` **một mình** (không có `top_msg_id`) **vào đúng topic** của tin đó và trả lời đúng tin; album gửi bằng `InputReplyToMessage(reply_to_msg_id, top_msg_id)` cũng vào đúng topic và trả lời đúng. Vậy `_reply_of` (reply thay chỗ topic) đủ cho đường tin đơn lẻ, không cần yêu cầu thô. **Chưa kiểm (khi chạy spike)**: reply sang tin ở *topic khác* (script không thử; tgmirror không gửi trường hợp đó vì so topic đích trước khi giữ reply, nên chỉ ảnh hưởng nếu so sai) và chạy `clone --keep-replies` thật từ đầu đến cuối. **Kiểm cả lệnh trên Telegram thật (người dùng, 2026-10-14)**: `clone --keep-replies` sang forum đích **giữ reply chính xác** và dòng kết quả **không có `reply_lost`** (không tin nào mất reply). Người dùng báo ngắn gọn, không ghi số liệu. Phần còn chưa kiểm ở trên (reply sang topic khác) vẫn chưa thử. **Đã làm ở 19c2** (2026-10-14; không migration, không bảng mới; **D2 không đổi**: mặc định vẫn là forward không tác giả, `keep` là công tắc tùy chọn đã nằm trong hướng được duyệt ở `07` mục 5.1): - `engine/transform.py`: `Transform.keep_forward_header` (khóa `forward_header: keep|drop`, mặc định `drop`; còn `links` là khóa đặt trước), kiểm trong `__post_init__` để cả đường cờ chồng lên (`dataclasses.replace`) cũng bị chặn. - `core/gateway.py`/`core/telethon_gateway.py`: `copy_messages(..., keep_header=False)` → `drop_author=None` thay cho `True` (đường tin thường lẫn `ForwardMessagesRequest` có `top_msg_id`). `engine/copy.py::copy_batch(keep_header=)`, `runner._send` truyền `transform.keep_forward_header`. - `engine/runs.py::check_options`: `forward_header_needs_forward` (mã 2) khi kèm `--mode reupload`, `--caption` khác keep, `--topic-as-hashtag`. - `cli/transform_options.py`: `--keep-forward-header` trên `clone` và `inspect --plan` (không có trên `restore`: restore luôn tải lên lại; file có `forward_header: keep` ở restore bị từ chối bằng chính lỗi trên). - Test mới: `tests/integration/test_runner_forward_header.py` (header mặc định/keep, album vẫn một nhóm, định tuyến vào topic vẫn là forward, nhớ theo cặp, các tổ hợp bị từ chối), ca model/CLI/restore trong `test_transform.py`, `test_cli_transform.py`, `test_cli_restore.py`; `FakeGateway.copy_messages` đặt/ bỏ `is_forward`/`fwd_from_id`. **Chọn lựa ở 19c2** (nêu để sửa nếu không hợp): 1. **Không ghép với mọi thứ buộc gửi lại** (thao tác `caption`, `strip`, `reply: keep`, `--mode reupload`, `--topic-as-hashtag`): header chỉ có trên forward, nên một tin vừa gửi lại vừa giữ header là không thể; chọn từ chối bằng mã 2 thay vì lặng lẽ mất một trong hai. Hệ quả: `--keep-forward-header --keep-replies` là lỗi; ai cần reply thì không có header. 2. **Định tuyến hashtag và `topic_map` đi cùng được** (chỉ là forward vào topic). 3. **Nguồn `noforwards`** vẫn không forward được dù có header hay không: hành vi hiện có (`ForwardsRestricted`), D3 không liên quan vì không tải gì. **Kiểm trên Telegram thật (người dùng chạy `scripts/spike_forward_header.py`, 2026-10-14, nguồn là kênh công khai, đích là kênh thường)**: một album (2 tin) và một tin thường forward **không `drop_author`**: cả ba tin ở đích **mang header** "Forwarded from" (kênh nguồn), album vẫn **một nhóm** (cùng `grouped_id`, một nhóm cho cả cuộc forward). Vậy `forward_header: keep` giữ album như `drop_author=True` (spike 5, vế album). **Còn chưa kiểm**: forward vào topic của forum (`top_msg_id`, chạy lại script với `--topic N` và đích là forum) có vào đúng topic không; header hiện thế nào với nguồn là kênh riêng tư/ẩn tên (Telegram có thể hiện tên ẩn hoặc không hiện); một lần `clone --keep-forward-header` từ đầu đến cuối. **Đã làm ở 19c3** (2026-10-14; không đụng D1–D10, không migration của DB; backup thêm một trường tùy chọn): - `core/links.py` (thuần): `parse_message_link` (`t.me//`, `t.me/c//`, kèm topic ở giữa với forum; loại link kênh, mời, `tg://`, trang web khác), `points_at`, `relinked` (viết lại giữ nguyên kiểu có/không `https://`). - `SrcMessage.own_links` / `ExportedMessage.own_links`: id các tin **của cùng chat** mà text/caption trỏ tới, lấy từ entity lúc đọc (`telethon_gateway._own_links`, dùng `_source_names` có sẵn, nên username lẫn `c/` đều nhận); lưu trong `messages.jsonl` (trường tùy chọn: backup cũ không có thì không viết lại link) và trong chỉ mục (`_TUPLES`). `BackupManifest.src_username` (tùy chọn) để restore nhận link `@username`; `FromBackup.src_username`. - `core/gateway.py`: `LinkRewrite(mapping, prefix)`, `CaptionPolicy.links`, `Unit.own_links`. `telethon_gateway._op_rewrite_links`: hyperlink (`MessageEntityTextUrl`) đổi địa chỉ, giữ chữ; link hiển thị (`MessageEntityUrl`) sửa trong text và entity quanh nó dịch theo UTF-16 (`_apply_edits`). Chạy **trước** các thao tác caption (để `strip_links: source` không xóa mất link vừa trỏ về đích) và áp cho cả tin chữ **không cần `text_too`** (link là thứ tạo nên tin chữ). - `engine/transform.py`: `Transform.rewrite_links` (`links: rewrite|keep`; khóa `links` hết bị đặt trước, `_RESERVED` bỏ); không đi cùng `forward_header: keep`. `engine/strategy.py`: `links_to_source`; router gửi lại unit có link tới chính chat. - `engine/runner.py::_link_targets`: tra `Store.dst_ids_of` (qua `msg_map` của **cặp**), dựng `LinkRewrite` với tiền tố `t.me/` (`RunOptions.dst_username`, đọc ở `begin_run`, thuộc về từng lần chạy) hoặc `t.me/c/`; đếm `links_left` vào `stats_json` (`Run.links_left`, dòng `run.links_left`). - `cli/transform_options.py`: `--rewrite-links` trên `clone`/`restore`/`inspect --plan`, ghép như các cờ khác. - Test mới: `tests/integration/test_runner_links.py` (9 ca), ca parse/rewrite trong `test_links.py`, `test_transform.py` (entity UTF-16, thứ tự với `strip_links`, tin chữ), ca CLI/restore, `FakeGateway` (`own_links`, viết lại link trong text). **Chọn lựa ở 19c3** (người dùng không phải quyết, nêu để sửa nếu không hợp): 1. **Chỉ link lùi** (07 mục 5.3): link tới tin chưa có bản sao lúc gửi **giữ nguyên** và được đếm (`links_left`); lượt sửa bù sau khi clone xong là việc của Phase 20 (`edit`), chưa có. 2. **Router không biết trước link có bản sao hay không**: mọi unit có link tới chính chat đều bị gửi lại, kể cả khi sau đó link không đổi được (cùng kiểu 19a mục 6 và 19c1 mục 1). Poll/game/invoice/loại không rõ vẫn được forward (link không đổi). 3. **Link tới chat khác không đụng**; link vào topic của forum (`t.me/c///`) thành link không có topic (`t.me/<đích>/`), Telegram vẫn mở đúng tin. 4. **Chỉ entity**: link không có entity (chữ trần mà Telegram không nhận là link) không đổi; backup làm trước 19c3 không có `own_links` nên restore từ nó không viết lại link (làm lại backup để có). 5. **Chỉ mục metadata cũ** thiếu `own_links` đọc ra rỗng; `clone` không đọc qua chỉ mục nên không ảnh hưởng, `inspect` không dùng trường này. **Kiểm trên Telegram thật (người dùng, 2026-10-14)**: `clone --rewrite-links` **viết lại link thành công** (link tới tin đã sao chép trỏ về bản sao ở đích). Người dùng báo ngắn gọn, không ghi từng ca hay số liệu. **Còn chưa nghe báo riêng**: link có topic của forum, kênh nguồn riêng tư (`t.me/c/...`) so với công khai, `restore` từ backup mới làm. ### Phase 18b — ghi chú (2026-10-14; xong code, chưa thử trên Telegram thật) **Làm theo thứ tự** (mỗi lát chạy được): sửa phân loại media → chỉ mục (`inspect` dùng nó mặc định) → `inspect --quick` → màn hình "Khám phá". Spike 1 (`scripts/spike_counters.py`, kết quả ở `07` mục 9) quyết định hình dạng của `--quick`. **Đã làm**: - **Sửa phân loại** (tìm ra nhờ spike 1, người dùng chọn làm trước 18b): `MediaKind.OTHER` (`--media other`) cho đính kèm không có tệp và không dựng lại được — `MessageMediaToDo` (checklist), `PaidMedia`, `Story`, `Giveaway`, `GiveawayResults`, `VideoStream`, `Unsupported` — trước đây rơi vào `document`. Chiến lược B coi `other` như `game`/`invoice` (`--ignore-unsupported`/`--placeholder`), backup ghi một bản ghi (`ExportedMedia(kind=other, title=...)`) thay vì một tin chữ rỗng, không đẩy xuống server, không có `NO_CAPTION`/`FILELESS` rắc rối: forward vẫn mang được. Dice vẫn là `document` (dựng lại được từ chính media của tin). - **Chỉ mục** (`store/index.py` SQL, `engine/index.py`: `update`, `IndexReader`, `find`; `Paths.index_dir`): một file SQLite mỗi nguồn, mỗi tin một dòng JSON của `SrcMessage` (mọi trường, đọc lại đủ), cộng `meta` (`last_id`, `updated_at`, `complete`, mô tả nguồn: id, tên, username, loại, `noforwards`, tiêu đề topic). Là một **tiền tố** theo id: dừng giữa chừng để lại một chỉ mục ngắn nhưng đúng, lần sau đọc tiếp từ `last_id` (tin dịch vụ không được lưu nhưng đẩy `last_id`). `inspect` đọc nguồn **qua chỉ mục theo mặc định** (cập nhật phần mới rồi báo cáo từ nó): lần đầu cùng chi phí quét cũ, các lần sau chỉ đọc tin mới. `IndexReader` là một `MessageReader`, nên `engine/inspect.scan` và `Matcher` không đổi — một nơi định nghĩa ngữ nghĩa lọc. - **Cờ của `inspect`**: `--refresh` (đọc lại cả nguồn, xong mới bỏ tin không còn — bắt tin đã sửa/xoá, lượt xem, reaction), `--offline` (dùng chỉ mục như đang có: không tài khoản, không Telegram; nhận id/`@username`/tên đúng của một nguồn đã xem), `--no-index` (quét sống như 18a, không lưu gì). Đầu ra ghi **chỉ mục cập nhật lúc nào** (một dòng ở báo cáo; `index{messages,last_id,updated_at,complete,offline}` ở `--json`). - **`inspect --quick`** (`MediaCounters`, `TelegramGateway.media_counters`, `FloodGuard` qua `_GuardedReader`): một request `messages.getSearchCounters` cho ảnh/video/tài liệu/nhạc/voice/video tròn/gif/link/vị trí, cả nguồn hoặc một topic (`--topic ID`, kể cả General = 1: spike 1 đã kiểm). Không đi cùng bộ lọc nào khác (số này không có khoảng id/ngày), không đi với thư mục backup. Loại Telegram không trả (danh bạ, poll, ghim) in "—". Nhãn nói rõ đây là cách phân loại của Telegram, lệch vài % so với quét (tin bị ẩn vì vi phạm điều khoản vẫn là "video" ở đó). - **Màn hình "Khám phá"** (`engine/explore.py` thuần, `ui/menu/screens/explore.py`, mục menu "Khám phá…" sau "Sao chép mới"): chọn nguồn bằng đúng câu hỏi của wizard clone, dựng/cập nhật chỉ mục (`q`/Esc dừng và dùng phần đã có), nạp cả chỉ mục vào bộ nhớ rồi mọi bước là **đếm lại trong bộ nhớ**, không gọi Telegram. Bốn bảng cạnh nhau (loại, tháng, hashtag + một bảng đổi bằng Tab: forward/domain/topic/người gửi); ←→ cột, ↑↓ dòng, Enter thêm vị từ vào **một** rule include (AND), `x` thêm rule exclude, Backspace bỏ bước cuối. Hành động: `l` danh sách tin khớp, `s` ghi `@last` (kèm id), `c`/`b` mở `CloneFlow`/`BackupFlow` với nguồn và filter đã điền (các câu hỏi còn lại — đích, D3, xác nhận — giữ nguyên), `u` cập nhật, `R` đọc lại cả nguồn. Luật 7: không có logic chỉ menu mới có — filter dựng từ `Step` đi qua `FilterSpec`/`Matcher` như cờ, và mọi hành động mở đúng flow của lệnh. - **Hạ tầng**: `engine/flood.py::inspect_guard` (một chỗ dựng `FloodGuard` cho cái nhìn chỉ đọc, `tgmirror inspect` và màn hình Khám phá dùng chung); `MenuKey.LEFT/RIGHT`. - **Test mới**: `test_index.py`, `test_cli_inspect_index.py` (cả `--quick`), `test_explore.py`, `test_menu_explore.py`, `test_telethon_gateway.py::test_media_counters_*`, các ca `OTHER` ở `test_telethon_messages.py`/`test_reupload.py`. Cả bộ: 2202 pass, 3 skip (trước 18b: 2146). **Khác với đề xuất ở `07` mục 3.4/4.5** (không đụng D1–D10): 1. **Thư mục chỉ mục là `/index/`** chứ không phải ``: cùng chỗ với `selections/`, tránh thêm một vị trí vào `Paths` (không đi theo `appdata export` vì export chỉ lấy `tgmirror.db` + `config.toml`). 2. **Chỉ mục lưu JSON của `SrcMessage`, không dựng cột SQL**: filter chạy bằng `Matcher` trên bộ nhớ đúng như `07` đề xuất; một dòng ~0,5 KB nên kênh 100.000 tin cỡ vài chục MB. **Đã đo trên kênh thật (2026-10-17, spike 6)**: ~0,7 KB một tin, xem "Đo trên kênh lớn" bên dưới. 3. **Mặc định đi qua chỉ mục** (cập nhật phần mới), không phải cờ bật: chi phí lần đầu như cũ, các lần sau rẻ hơn hẳn. `--offline` là cách "không gọi Telegram" của `07`; `--no-index` giữ lối quét sống cho ai cần. 4. **Một chỉ mục lạc hậu trong delta**: tin đã sửa/xoá và số lượt xem/reaction chỉ làm mới bằng `--refresh` (hoặc `R` trong màn hình). Mọi đầu ra nói điều đó; không có phát hiện tự động. 5. **Chỉ mục không bao giờ là căn cứ để ghi** (như `07` mục 3.4): không có đường nào dùng nó cho clone/backup; `IndexReader` từ chối `fetch`/`prepare`/`export_unit`. 6. **Màn hình Khám phá chưa có `e`/`d`** (sửa/xoá tại chỗ): thuộc Phase 20 (D10); các phím được để trống. 7. **Một include cùng loại thay vì cộng**: chọn `video` rồi `photo` thì giữ `photo` (hai danh sách "bất kỳ trong" không AND được trong một rule); loại một tháng (exclude) không có vị từ nên báo thay vì lờ đi. **Kiểm trên Telegram thật (người dùng, 2026-10-14)**: chỉ mục (`inspect` lần đầu rồi lần hai, `--offline`, `--refresh`) và màn hình Khám phá **pass**. `inspect --quick --topic 9496` trên một forum thật **thất bại**: `GetSearchCountersRequest` trả `RpcCallFailError` cả sáu lần Telethon thử, rồi Telethon ném một `ValueError("Request was unsuccessful 6 time(s)")` trần mà `map_exception` không biết, nên người dùng thấy "Có lỗi ngoài dự kiến". Sửa: `ValueError` đó thành `ServerFailed` (lớp con của `Transient`, câu thông báo riêng nói đây là lỗi nội bộ của Telegram, gợi ý `--quick` không kèm `--topic` hay quét bằng `inspect`); cũng sửa gợi ý `--debug` (là cờ toàn cục, đứng **trước** tên lệnh: `tgmirror --debug inspect ...`). Cùng lỗi trước đó làm một `run` gặp `RpcCallFailError` liên tục thành crash thay vì `Transient`. **Nguyên nhân**: chạy lại cùng nguồn với `--topic 1` thì **ổn**, chỉ `--topic 9496` lỗi — id đó không trả được số đếm; người dùng đối chiếu: 9496 **có** trong `tgmirror topics`, nên đây là giới hạn phía server — nhiều khả năng do topic lớn (chưa kiểm số tin của nó). Vì một id không phải topic làm Telegram trả sáu lỗi nội bộ liền, `--quick --topic N` nay **hỏi danh sách topic trước** (một request đọc) và nói thẳng "forum này không có topic N" / "nguồn không phải forum" (mã 2) thay vì gửi request hỏng; nếu topic có trong danh sách mà server vẫn lỗi thì câu `ServerFailed` ở trên mới hiện ra. **Đo trên kênh lớn (người dùng, 2026-10-17, `tgmirror inspect --refresh`)**: một kênh thật 60.395 tin (28.727 đơn vị, 9.560 album; 37.020 video + 22.972 ảnh = 1,9 TB; từ 2020-07-05 đến 2026-10-16, id tới ~63.000, mật độ ~95%). Quét đầy đủ chạy hết, không FloodWait, không lỗi: tiến độ in mỗi ~500 tin (121 dòng), đọc nhanh nhất ở phần đầu. Chỉ mục: **43.134.976 byte (~41 MB), ~714 byte một tin**, cao hơn ~0,5 KB ước ở mục 2 (JSON đủ mọi trường, caption dài, hashtag, entity) — ngoại suy: 100.000 tin ≈ 70 MB. Báo cáo ra đủ các bảng theo loại media, tháng (72 tháng) và hashtag (top 10 + "khác: 47 mục") và dòng "Dùng tiếp với đúng filter này". **Chưa đo**: thời gian quét (không bấm giờ), thời gian nạp chỉ mục vào bộ nhớ ở màn hình Khám phá. Một quan sát nhỏ: sau khi quét còn một dòng `Đang đọc: 1 tin (tới id 4)...` (nhịp đầu của lượt đếm trên chỉ mục, vô hại nhưng dễ gây hiểu nhầm là đang đọc lại từ đầu). **Chưa kiểm trên Telegram thật** (người dùng chạy): cập nhật chỉ mục delta khi tin đã được sửa; màn hình Khám phá trên kênh lớn (thời gian nạp và đếm lại ở ~100.000 tin — bộ đếm chạy trên luồng chính, có thể thấy khựng); spike 6 (cỡ chỉ mục và thời gian quét 100.000 tin). ### Phase 19d — kế hoạch (duyệt hướng 2026-10-15; 19d1 và 19d2 xong code 2026-10-15, 19d3 chưa) Thay `daily_cap` cố định bằng rate limit gắn với các yếu tố ảnh hưởng tới nó. Thiết kế, bảng yếu tố, đánh đổi và các phương án đã loại nằm ở `05-chong-flood.md`, "Kế hoạch: rate limit thích nghi". Không đổi D1–D10. Ba lát cắt, mỗi lát một commit chạy được. **19d1 và 19d2 nằm trong release 0.2.0** (người dùng chốt 2026-10-15: với 5000 tin và mốc 00:00, trải nghiệm hiện tại gần như không dùng được), nên 19d2 không đợi dữ liệu thật của 19d1. Nó dùng ngưỡng tạm, và dữ liệu `flood_log` sau phát hành sẽ chỉnh ngưỡng ở bản vá. 19d3 vẫn tùy chọn, không thuộc 0.2.0. **19d1 — đo trước, không đổi hành vi giới hạn** (rẻ, gần như không rủi ro). **Xong code 2026-10-15**, chi tiết cài đặt ở cuối mục này ("19d1 — đã cài"): - Migration: `flood_log` thêm `dst`, `action`, `sent_1h`, `sent_24h`, `premium`. `kind` thêm `premium_wait` (`FLOOD_PREMIUM_WAIT_X`, trước đây rơi vào `flood_wait`). - Đếm tin đã gửi theo xô giờ cho mỗi khóa `(account, action, dst)`, để biết `sent_1h`/`sent_24h` lúc bị flood. Cap vẫn tính như cũ. - Đọc `slowmode_seconds` của đích trong phần chuẩn bị một lần của lần chạy (`gateway.channel_info` hoặc một lời gọi mới, chọn khi cài), và dùng làm sàn delay ghi cho đích đó. - Tách delay theo loại hành động (`forward`/`send` cho ghi; `history`/`file` cho đọc). Đọc có delay AIMD riêng, không còn nhân theo delay ghi. - `tgmirror history n` và `status` hiện thêm cột hành động/đích của các lần flood. - Chạm: `core/limiter.py`, `engine/flood.py` (mỗi lời gọi khai báo `action`), `core/gateway.py` + `telethon_gateway.py` (slow mode, Premium, `FLOOD_PREMIUM_WAIT` trong `map_exception`), `store/schema.sql` + migration, `store/floodlog.py`, `store/limiterstate.py`, `engine/status.py`, test limiter/flood/store. - **Hoàn thành khi**: mỗi dòng `flood_log` mới đủ ngữ cảnh để trả lời "flood dài xảy ra sau bao nhiêu tin trong 1 giờ/24 giờ, ở hành động nào, đích nào"; một đích có slow mode 30 s không bao giờ bị ghi nhanh hơn 30 s; toàn bộ test cũ vẫn xanh. - **Sau 19d1, việc của người dùng** (không còn chặn 19d2, xem trên): dùng bình thường rồi gửi lại `flood_log` (hoặc `tgmirror history`) để chỉnh ngưỡng `short_flood` và kiểm hai giả thuyết (giới hạn ghi tính theo từng đích; `X` dài ứng với hạn mức cửa sổ). Nếu dữ liệu bác bỏ giả thuyết thì sửa ở bản vá sau 0.2.0. **19d1 — đã cài (2026-10-15)**: - Migration 4 (`store/db.py::_V4_LANES`): `flood_log` thêm `dst`, `action`, `sent_1h`, `sent_24h`, `premium`; bảng `limiter_lanes` (delay từng làn) và `sent_hours` (xô giờ UTC, giữ 24 giờ). `limiter_state` giữ nguyên, `delay_ms` giờ là delay cao nhất của các làn ghi. Có test nâng cấp từ v3. - `core/limiter.py`: `Limiter` có làn `(action, dst)` cho ghi, `action` cho đọc; `acquire(..., action=, dst=)`, `on_success(cost, action, dst)`, `on_read_success`, `on_flood(action, dst)`, `delay_of`, `set_slow_mode`, `sent_in`. Gọi không có `action` thì là làn `send`/`history` mặc định, nên cách dùng cũ vẫn chạy. Throttle (ba flood/10 phút) và `daily_cap` vẫn là của cả account. - `engine/flood.py`: `LANES` ánh xạ phương thức → làn; `FloodOwner.dst` (đích của lần chạy); `FloodGuard.pace(cost, credit, action)`; `_GuardedReader` rút gọn về một `_call` chung và báo `read_done`; `learn_context` đọc Premium và slow mode của đích một lần ở đầu lần chạy (`Runner.run`, `BackupWriter.run` chỉ Premium). - Gateway: `slowmode_seconds(chat)` (`GetFullChannelRequest`, 0 cho kênh broadcast/nhóm cũ — runner không gọi cho các loại đó) và `is_premium()` (`get_me().premium`); `FLOOD_PREMIUM_WAIT_X` map thành `FloodWait(premium=True)`, `kind = premium_wait`. - Hiển thị: `history n` (và JSON) có làn, đích, `sent_1h`/`sent_24h`; `status` ghi `loại/làn` (`ui/lines.py::flood_kind`, `flood_where`). Thông báo `run.slow_mode` một lần khi đích có slow mode. - **Khác bản kế hoạch**: (1) khóa đọc là `(action)` không theo đích, như đề xuất; (2) `premium_wait` hiện vẫn *tăng delay* của làn như mọi flood (kế hoạch muốn không đụng delay ghi và giảm `RequestBudget`; việc đó chạm vào pool truyền file, để 19d2 sau khi có dữ liệu); (3) sàn slow mode áp cả khi tài khoản là admin; (4) `sent_1h`/`sent_24h` xấp xỉ theo xô giờ (xô cũ nhất tính theo phần còn nằm trong cửa sổ), đủ để phân tích nhưng không phải số đếm chính xác theo phút; (5) hai lời gọi mới là một-lần ở đầu lần chạy (ngoại lệ của luật 1, như `last_message_id`), một lần chạy trên đích broadcast tốn thêm đúng một request (`is_premium`); (6) `scripts/mutation_check.py` chưa thêm cơ chế mới (làm ở 19d2 cùng ngân sách). - **Chưa kiểm trên Telegram thật**: `slowmode_seconds` trên supergroup/forum có slow mode thật (chỉ đọc `full_chat.slowmode_seconds`, chưa thử), `get_me().premium`, tên lỗi `FLOOD_PREMIUM_WAIT` khớp `FloodPremiumWaitError`. **19d2 — ngân sách tự học, cửa sổ trượt, `daily_cap` chỉ cảnh báo** (thuộc 0.2.0; theo câu trả lời của người dùng 2026-10-15, dưới): - **Phân loại FloodWait theo `X`**, ngưỡng `short_flood` tạm là 60 s (khóa `[limits]` mới để chỉnh được mà không cần bản mới): ngắn thì AIMD delay của làn đó, như 19d1; dài thì cắt ngân sách cửa sổ của làn đó. - **Ngân sách cửa sổ trượt theo làn ghi là cái phanh duy nhất chặn lần chạy.** Một làn **chưa có ngân sách cho tới khi gặp flood dài đầu tiên**: lúc đó chỉ pacing (delay, jitter, nghỉ dài) và FloodWait giới hạn nó. Gặp flood dài thì ngân sách = khoảng 80% số tin làn đó đã gửi trong cửa sổ tương ứng (`X` ≤ 1 giờ là cửa sổ 1 giờ, dài hơn là cửa sổ 24 giờ; giả thuyết, kiểm bằng dữ liệu sau phát hành). Flood dài lần sau trên làn đã có ngân sách thì × 0,5. Cứ 24 giờ liền không có flood dài thì +10%, có sàn. Lưu theo làn (cột mới của `limiter_lanes` hoặc bảng mới, migration 5). Xô giờ `sent_hours` của 19d1 là bộ đếm của cửa sổ. - **Cửa sổ trượt thay cho mốc 00:00** (bỏ hẳn `day`/`sent_today` khỏi việc chặn): batch mà `sent_in(cửa sổ) + cost > ngân sách` thì lần chạy dừng ở `waiting_flood`, `resume_at` = lúc cửa sổ nhả đủ chỗ cho batch đó. Giữ `fail_reason='daily_cap'` (đổi tên ngoại lệ thành `BudgetReached` được, nhưng không đổi giá trị trong DB) để không vỡ `history` cũ. Vẫn giữ luật "batch đầu tiên lớn hơn ngân sách vẫn đi" để không kẹt vĩnh viễn. - **`daily_cap` thành trần an toàn chỉ cảnh báo, không chặn**: khi `sent_24h` của account (mọi làn ghi cộng lại, cửa sổ trượt) vượt `daily_cap`, in một cảnh báo (một lần cho mỗi lần chạy, và một lần nữa nếu vượt gấp đôi), ghi vào dòng kết quả của lần chạy, rồi chạy tiếp. Mặc định giữ 5000 (bây giờ nó chỉ là ngưỡng để nhắc). `check_cap` cũ trước khi đẩy byte chuyển sang kiểm ngân sách của làn. - **Hiển thị**: `status`, dòng mở đầu lần chạy và pre-flight nói số tin đã gửi trong 24 giờ qua (không còn "hôm nay"), ngân sách hiện hành của từng làn (hay "chưa học") và lần flood dài đã đặt ra nó. `cap_days` tính theo ngân sách đã học; một làn chưa có ngân sách thì không ước lượng số ngày, chỉ ước lượng thời gian theo pacing. Pre-flight của `inspect --plan` cũng vậy. - Cập nhật `05` (mô tả limiter hiện hành; bỏ đoạn "Daily cap" kiểu cũ), `04-state-checkpoint.md` (schema, `resume_at`), `02-cli-ux.md` (`status`, `config`, mã thoát 3 khi hết ngân sách), README (dòng `daily_cap` theo ngày lịch của container: không còn đúng), skill `flood-safety` và `checkpoint-state`, `CLAUDE.md` (mục `core/limiter.py`), `scripts/mutation_check.py` (cơ chế mới: ngân sách, cửa sổ trượt). - **Hoàn thành khi** (đồng hồ giả): gửi quá `daily_cap` chỉ in cảnh báo và lần chạy vẫn tiếp; một làn chưa từng gặp flood dài không bao giờ bị chặn vì ngân sách; một flood dài chỉ đặt/cắt ngân sách của đúng làn bị chặn, ghi vào đích khác hay đọc không bị chậm theo; lần chạy kế tiếp không vượt ngân sách đã học, và `resume_at` là lúc cửa sổ nhả chỗ (không phải nửa đêm); 24 giờ không flood dài thì ngân sách tăng lại; DB cũ (v4, có `sent_today`) nâng cấp được; `mutation_check` không còn cơ chế mới nào mà test không nhận ra. **19d2 — đã cài (2026-10-15)**: - `core/config.py`: `[limits] short_flood` (int, mặc định 60). `daily_cap` giữ 5000 nhưng chỉ là ngưỡng nhắc. - `core/limiter.py`: `LaneBudget` (`amount`, `window_hours`, `since`, `flood_at`, `flood_seconds`), `LaneState.budget`; `on_flood(action, dst, seconds=, quota=)` đặt/cắt ngân sách (80%, ×0,5, sàn `MIN_BUDGET` = 20, cửa sổ 1 giờ nếu `X` ≤ 3600 s) thay vì nhân đôi delay cho `FLOOD_WAIT` dài trên làn ghi; `check_budget(cost, action, dst)` thay `check_cap` và dựa vào `window_sent` trên xô giờ; `_resume_at` (xô cũ nhất hết hạn đủ chỗ); `grow_budget` (+10% mỗi 24 giờ, hàm thuần, `status` cũng dùng); `cap_warning` (1× và 2× `daily_cap` trên tổng 24 giờ của account); `budget_of`, `budgets_for`, `sent_total`. - `core/errors.py`: `DailyCapReached` đổi tên `BudgetReached(resume_at, sent, budget, window_hours, action, dst)`; `fail_reason` vẫn là `daily_cap`. - Migration 5 (`_V5_BUDGETS`): các cột ngân sách trên `limiter_lanes`; `limiterstate` đọc/ghi chúng. `limiter_state.day`/`sent_today` vẫn được ghi (DB cũ, `LimiterState` cũ), nhưng không còn chặn gì và `status` không dùng. - `engine/flood.py`: `FloodGuard.check_budget`, thông báo `cap_warning` và `budget_learned` (ngân sách học được ngay khi gặp flood dài); slow mode/transport/premium không bao giờ là hạn mức. - `engine/runner.py`: `_rest` (ngày nghỉ theo ngân sách của đích, bỏ qua làn chưa học) thay `_cap_days`; `check_budget` trước khi đẩy byte. - `engine/status.py`: `sent_24h`, `budgets`, `BudgetInfo`, `cap_days(left, budget, sent, window_hours)`; `ui/lines.py::budget_lines` cho `status` (CLI và menu); JSON `limiter.sent_24h`, `limiter.budgets`. Pre-flight bỏ `days` (không có đích thì không có ngân sách). - `scripts/mutation_check.py`: 8 cơ chế mới (ngân sách không đặt/không chặn/không tăng lại, `resume_at` đã qua, sàn slow mode, `quota`, cảnh báo cap) và `test_runner_flood.py` vào danh sách test. - **Khác bản kế hoạch**: (1) cảnh báo `daily_cap` chỉ là thông báo trên luồng, không ghi vào dòng kết quả của lần chạy; (2) `premium_wait` vẫn tăng delay của làn (chưa giảm `RequestBudget`); (3) `short_flood` mặc định 60 s là con số tạm, chưa có dữ liệu thật; (4) cắt ngân sách dựa trên số tin của đúng làn trong cửa sổ, nên một làn `send` và một làn `forward` học riêng; (5) một lần flood dài với `--wait` vẫn đặt ngân sách rồi ngủ tiếp, lần chạy sau bị giới hạn bởi nó. - **Chưa kiểm trên Telegram thật**: giả thuyết `X` ≤ 1 giờ ↔ cửa sổ 1 giờ, `X` dài ↔ 24 giờ; giả thuyết giới hạn ghi theo từng đích; `resume_at` khớp với lúc Telegram nhả thật. Người dùng gửi lại `flood_log`/`history` sau một thời gian để chỉnh `short_flood` và 80%/×0,5/+10%. **Điểm dữ liệu đầu tiên 2026-10-16** (flood dài 1737 s trên làn `send` vào forum vừa tạo, 31 phút sau khi bắt đầu, 1907 tin trong 575 lời gọi chủ yếu là album; forward hơn 3.000 tin/giờ vào broadcast không bị chặn): ghi ở spike 15. **19d2 — sửa sau lần chạy thật (2026-10-17)** (hai lỗi của spike 15, lần chạy 69; không đụng D1–D10): - **Thời gian nghỉ tính bằng giờ**: `engine/status.py::cap_days` (làm tròn lên ngày) thành `rest_hours` (một cửa sổ cho mỗi `ngân sách` tin không vừa phần còn lại của cửa sổ hiện tại, nhân số giờ của cửa sổ). `StatusReport.cap_days` thành `cap_rest_hours`; thông báo `run.cap_days` thành `run.cap_rest` (tham số `hours`); `ui/lines.py::rest_phrase` nói `N giờ`, hoặc `N ngày` khi đúng bội số của 24 giờ. Lần chạy 69 giờ báo "khoảng 2 giờ" thay vì "1 ngày". JSON của `status` có thêm `cap_rest_hours`, `cap_rest_days` giữ nguyên tên (làm tròn lên ngày, cho máy đọc cũ). - **Ô đếm 5 phút thay ô 1 giờ**: `SentHour`/`LimiterState.hours`/bảng `sent_hours` thành `SentBucket`/`.buckets`/`sent_buckets` (`bucket` = `unix // 300`, giữ 24 giờ = 288 ô một làn). `window_sent` và `Limiter._resume_at` tính theo ô nên cửa sổ nhả tin trễ tối đa 5 phút (trước đây tới 1 giờ: lần chạy 69 dừng 02:32 phải đợi tới 04:00 thay vì khoảng 03:20). Migration 6 đổi tên bảng/cột và dời mỗi giờ cũ về ô cuối của nó (`hour × 12 + 11`), nên số cũ chỉ có thể bị nhả muộn, không bao giờ sớm. - **Test**: `test_limiter.py` (lần chạy 69 dựng lại: nghỉ dưới 1 giờ; một tin ra khỏi cửa sổ trong 5 phút), `test_store.py::test_v6_migration_…`, `test_status.py` (`rest_hours`: 3082 tin trên 1506/giờ cần 2 giờ), `test_lines.py` (`rest_phrase`, `LineReporter` nói giờ cho ngân sách 1 giờ), `test_runner_analysis.py` (`cap_rest` có `hours`). `scripts/mutation_check.py` đổi mẫu `resume_at` sang tên ô. - **Đã kiểm trên Telegram thật (người dùng, 2026-10-17, lần chạy 70)**: câu "cần nghỉ thêm khoảng 1 giờ" đúng đơn vị; `resume_at` sát (đợi 44 phút thay vì tới 06:00 UTC). Xem spike 15. **19d3 — Takeout cho phía đọc (tùy chọn, làm khi cần)**: đọc của `backup`/`inspect`/chỉ mục đi qua `invokeWithTakeout` trong gateway, vẫn qua `FloodGuard`. Phải xử lý được `TAKEOUT_INIT_DELAY_X` (người dùng xác nhận trên thiết bị khác, hoặc chờ) và lùi về đọc thường khi bị từ chối. Không dùng cho phía ghi của clone. Trước khi code cần một spike (`scripts/spike_takeout.py`, người dùng chạy) đo xem `getHistory` qua Takeout có ít flood hơn thật không. **Người dùng trả lời (2026-10-15)**: 1. **`daily_cap` thành trần an toàn: cảnh báo khi chạm tới, không chặn.** Cái phanh chặn lần chạy chỉ còn là ngân sách học được từ flood dài của chính Telegram (19d2 ở trên). 2. **Cửa sổ trượt 24 giờ** thay cho mốc 00:00 giờ máy. 3. **Release 0.2.0**: 19d1 và 19d2 đều thuộc 0.2.0, trước khi tag. **Chọn lựa đề xuất** (người dùng không cần quyết, nêu để sửa nếu không hợp): khóa đọc không gồm nguồn (giới hạn đọc giả định theo account); ngưỡng `short_flood` tạm là 60 s cho tới khi có dữ liệu; Premium chỉ ảnh hưởng truyền file; làn chưa gặp flood dài thì không có ngân sách (không lấy 5000 làm điểm xuất phát, vì như vậy sẽ chặn đúng như hôm nay, trái với câu trả lời 1). ### Phase 19d4 — kế hoạch (2026-10-17; phần kèm 0.2.0 đã code, xem "19d4 — đã cài" bên dưới) Sinh ra từ một điểm mù người dùng chỉ ra sau lần chạy 69, 70 (spike 15): ngân sách học được vừa là phanh vừa là thứ duy nhất tgmirror học từ, nên một khi nó đã thấp hơn hạn mức thật thì không có gì đẩy nó lên ngoài +10%/24 giờ theo đồng hồ (1506 lên gấp đôi mất khoảng 7 ngày, lên gấp mười mất khoảng một tháng, và nó tăng dù làn có chạm phanh hay không). Hạn mức thật có thể cao hơn nhiều (tài khoản già đi, Telegram nới). Thiết kế và đánh đổi ở `05-chong-flood.md`, "Kế hoạch: thăm dò giới hạn". Không đổi D1–D10 (D6 giữ nguyên). **Người dùng chốt (2026-10-17)**: 1. **Reset/thăm dò là hành động chủ động.** Có cờ thì làm luôn, không hỏi lại. Không có cờ mà lần chạy đang ở trong giới hạn thì hỏi người dùng. 2. **Các cờ này không thuộc về lần chạy hay cặp.** Khái niệm chung: một tùy chọn không đổi bộ lọc thì không đổi "job" (cặp nguồn/đích); người dùng chạy lại cùng một cặp với tùy chọn khác nhau. Chỉ khi bộ lọc khác thì mới đọc lại từ đầu, hoặc người dùng ép làm lại bằng cờ (`--fresh`). Điều này **đã đúng với code hiện tại**: cặp được định danh chỉ bởi `(src_id, dst_id)` (`mirrors_pair`), `Store.start_run` đọc lại từ đầu chỉ khi filter đổi hoặc có `--fresh`, và mọi tùy chọn khác dùng lại cặp. Việc phải làm là xếp `--probe` và `--reset-limits` vào nhóm "chỉ của một lần chạy" của `RunOptions` (không vào `for_pair`, như `retry_of`, `from_backup`), và có test chứng minh một lần chạy với cờ này tiếp tục con trỏ của cặp, không tạo `mirrors` mới, không đổi `filters_json`. 3. **Tự hỏi khi không có cờ, thời điểm hỏi theo tuổi của lần kiểm chứng giới hạn.** Giới hạn lâu chưa được kiểm chứng thì hỏi người dùng có thử kiểm chứng để cập nhật không. **Người dùng trả lời ba câu hỏi đề xuất (2026-10-17)**: (a) **đồng ý** tách release: `tgmirror limits`, `tgmirror limits reset` và `--reset-limits` (rẻ, an toàn, không cần dữ liệu thêm) kèm 0.2.0, **cùng migration 7 (`bad_amount`/`bad_at`, và `ok_amount`/`checked_at`/`probe_fails` cho đủ bộ) và trần 95% của `bad` cho tăng theo đồng hồ**, vì `grow_budget` hiện không có trần và sẽ vượt `bad` = 1882 từ 2026-10-19 17:05 UTC; `--probe`, thăm dò, nhích `ok` và câu hỏi tự động làm sau 0.2.0 vì mới có một điểm dữ liệu; (b) tăng +10%/24 giờ theo đồng hồ: **giữ**, tăng tới 95% của `bad` rồi giữ nguyên; khi `bad` hết hạn vẫn dùng mức đang có cho tới khi thăm dò hoặc bị chặn (người dùng chốt sau khi nghe giải thích đánh đổi, 2026-10-17); (c) **đồng ý** không hỏi khi giới hạn vừa được kiểm chứng gần đây, chỉ in lần thử cuối và cách dùng `--probe`. **Thiết kế đề xuất** (chi tiết ở `05`): - **Trạng thái mỗi làn ghi** (`limiter_lanes`, migration 7): `ok_amount` (mức cao nhất đã chạy sạch một cửa sổ khi làn thực sự bị ngân sách giữ), `bad_amount`/`bad_at` (mức thấp nhất đã gây flood dài), `checked_at` (lần cuối giới hạn được đem ra thử: một flood dài, hoặc một lần thăm dò sạch), `probe_fails`. `budget` hiện có trở thành mức đang nhắm tới. Migration cho một ngân sách đã học: `ok = budget`, `bad = round(budget / 0.8)` (đúng số tin lúc bị chặn: 1882 của lần chạy 68), `checked_at = budget_since`. - **Một lần thăm dò** nâng trần của lần chạy lên giữa `ok` và `bad` (không có `bad` hay `bad` đã hết hạn: `ok × 1,25`). Chạy sạch tới trần thì `ok` lên trần và `checked_at` đổi. Flood trong lúc thăm dò thì `bad` = số đã gửi, ngân sách về `ok` (**không** cắt một nửa), `probe_fails` tăng (hỏi thưa dần). Flood khi chưa vượt `ok` mới là bằng chứng giới hạn xấu đi: cắt như hiện nay. Mỗi lần chạy chỉ thăm dò một bước. - **Tăng +10%/24 giờ theo đồng hồ giữ lại, có trần 95% của `bad` và chỗ dừng** (người dùng chốt 2026-10-17): chạm trần thì giữ nguyên cho tới khi người dùng chọn thăm dò hoặc làn bị chặn; khi `bad` hết hạn mức đang dùng vẫn giữ (không hạ, không tăng tiếp) cho tới khi thăm dò hoặc bị chặn. Chi tiết và đánh đổi ở `05`. - **Cờ** (cho `clone`/`run`/`retry`; `backup`/`inspect` chỉ đọc nên không có): `--probe` (thăm dò một bước, coi như đã đồng ý nhận một flood nếu hỏng), `--reset-limits` (quên ngân sách của các làn ghi vào đích này, không hỏi; làn quay về "chưa học"). `--yes` **không** thay cho `--probe` (cùng tinh thần D3: sự đồng ý rủi ro phải được nói ra), trả lời "giữ nguyên" cho câu hỏi. - **Lệnh `tgmirror limits`** (hiện từng làn: `ok`, `bad`, ngân sách, `checked_at`, số lần thăm dò hỏng) và `tgmirror limits reset [--dst ĐÍCH | --all]` (chủ động, không hỏi). - **Câu hỏi** (chỉ khi có terminal, trong `CloneFlow` và menu qua cùng một đường): hỏi **ở đầu lần chạy**, sau bước phân tích, không giữa lúc đang chạy (màn hình tiến độ đang vẽ). Điều kiện: có cờ thì không hỏi; không thì hỏi khi lần chạy này **sẽ chạm** ngân sách của một làn (tổng còn lại lớn hơn chỗ trống trong cửa sổ, hoặc làn đang kín sẵn) **và** `checked_at` cũ hơn `[limits] probe_after_hours` (mặc định 168 = 7 ngày, nhân 2 sau mỗi lần thăm dò hỏng, tối đa 30 ngày). Giới hạn vừa mới được thử thì không hỏi, chỉ nói lần thử cuối và cách dùng `--probe`. Ba lựa chọn: giữ ngân sách / thăm dò một bước / quên giới hạn. Không có terminal thì không bao giờ hỏi và không bao giờ tự thăm dò. - `flood_log` thêm cột `probe` để tách flood do thăm dò khỏi flood tự nhiên khi phân tích spike 15. - **Chạm**: `core/limiter.py` (`LaneBudget`, `grow_budget` có trần 95% của `bad` và dừng khi không còn `bad`; thăm dò), `core/config.py` (`probe_after_hours`, `probe_step`), `store/db.py` (migration 7) + `limiterstate.py` + `floodlog.py`, `store/runs.py` (`RunOptions.probe`/`reset_limits`, chỉ của một lần chạy), `engine/flood.py`, `engine/runner.py`, `cli/commands/{clone,run,retry}.py` + `limits.py` mới, `cli/wizard.py`, `ui/menu`, `ui/messages.py`, `engine/status.py`/`ui/lines.py` (`status` nói `ok`/`bad`/lần kiểm chứng cuối), `scripts/mutation_check.py`. - **Hoàn thành khi** (đồng hồ giả): ngân sách tăng 10% mỗi ngày nhưng không bao giờ vượt `floor(0.95 × bad)`, chạm trần thì đứng yên nhiều ngày; `bad` hết hạn thì mức đang dùng vẫn giữ nguyên và không tăng; một flood khi ngân sách đang cao hơn `ok` hạ `bad` và đưa ngân sách về `ok`; `ok=1506, bad=1882` thăm dò tới ≈1694 rồi ≈1788 rồi hội tụ; một thăm dò hỏng đưa ngân sách về `ok` chứ không halve và giãn câu hỏi; câu hỏi hiện đúng khi (chạm ngân sách ∧ lâu chưa kiểm chứng) và chỉ khi đó; `--reset-limits` không hỏi và không thấy phanh nào sau đó; `--probe` không tạo `mirrors` mới và không đổi `filters_json`/cursor; `--yes` không thăm dò; không có terminal không bao giờ hỏi; DB cũ (v6) nâng cấp được. ### 19d4 — đã cài (2026-10-17, phần kèm 0.2.0) Theo (a) ở trên: cài phần rẻ và an toàn, để `--probe` cho sau 0.2.0. Không đổi D1–D10. - **Mô hình**: `LaneBudget` thêm `ok`, `bad`, `bad_at`, `checked_at`, `probe_fails` (migration 7 trên `limiter_lanes`; ngân sách đã học được điền `ok = budget`, `bad = budget × 5 / 4`, `bad_at = flood_at`, `checked_at = budget_since`). Flood dài đặt `bad` = thấp hơn của `bad` cũ và số đã gửi, `bad_at` = `checked_at` = bây giờ. - **Tăng theo đồng hồ** (`grow_budget`): +10%/24 giờ nhưng không quá `floor(0.95 × bad)`, không bao giờ hạ một ngân sách đã ở trên trần, và dừng hẳn khi không có `bad` hoặc `bad_at` cũ hơn `[limits] probe_after_hours` (mới, mặc định 168; mức đang dùng giữ nguyên). - **Flood dài trên ngân sách đã tăng quá `ok`** đưa ngân sách về `ok` (không chia đôi), `bad` = số đã gửi, `probe_fails += 1`; flood khi chưa vượt `ok` (hay chưa biết `ok`) chia đôi như 19d2 và quên `ok`. - **Lệnh**: `tgmirror limits [--json]`, `tgmirror limits reset [--dst ĐÍCH | --all]` (`cli/commands/limits.py`, `engine/limits.py`; từ chối khi có lần chạy/backup đang chạy), `--reset-limits` trên `clone`/`run`/`retry` (`RunRequest.reset_limits` → `RunOptions.reset_limits`, chỉ của một lần chạy; `Runner.run` gọi `Limiter.forget_budgets(dst)` rồi lưu). `status` thêm dòng `Giới hạn:` và `ok`/`bad`/`checked_at` trong `--json`. - **Khác bản kế hoạch**: trần là `floor(0.95 × bad)` = 1787 cho `bad = 1882` (kế hoạch viết 1788); `ok` chỉ nhận giá trị từ migration vì chưa có thăm dò hay nhích `ok`, nên một ngân sách vừa học (không qua migration) có `ok = None` cho tới khi bị quên/đặt lại; cột `flood_log.probe` để cùng `--probe`. - **Test**: `test_limiter.py` (trần, hết hạn, về `ok`, `bad` thấp nhất, `forget_budgets`), `test_store.py::test_v7_migration_…` (và khứ hồi, `forget_budgets`), `test_status.py`, `test_lines.py`, `test_cli_limits.py` (lệnh, `--reset-limits` trên `clone`/`run`/`retry`, không đổi cặp/filter/con trỏ), `test_runner_flood.py`. `scripts/mutation_check.py` thêm 7 cơ chế (chạy tay). ### Phase 20 — ghi chú (bắt đầu 2026-10-18; lát 20.1 `delete` xong code và đã thử trên Telegram thật 2026-10-23; lát 20.2 xong code 2026-10-23, thử thật 2026-10-24) **Chia lát cắt** (như 11a/11b, 19a–c; không đổi D1–D10, D10 đã duyệt 2026-10-12), mỗi lát một commit chạy được: 1. **20.1 `delete`** — *xong code 2026-10-18*. Nền cho cả Phase 20: migration 8 (`ops`, `op_items`, `flood_log.op_id`), `Store` (`create_op`, `start_op`, `mark_op_items`, `op_units`, ...), gateway `delete_messages` (+ `FakeGateway`, `MessageDeleteForbidden` → `NoPermission`), làn `delete` của limiter, `FloodOwner.of_op`, `engine/ops.py` (`plan_delete`, `begin_op`, `OpRunner`), `tgmirror delete`, `O` trong `history`, `pause`/`stop` tới được thao tác, luật cứng 11 trong `CLAUDE.md`. 2. **20.2** — *xong code 2026-10-23, đã thử thật 2026-10-24; chi tiết ở "20.2 — đã cài" dưới đây*: hỏi backup trước khi xoá (Q5, `--backup-to DIR`/`--no-backup`; D3 áp cho bước backup), `O` trong `status`, mục trong menu/`TaskScreen`, wizard chọn filter từ màn hình Khám phá (phím `d`). 3. **20.3** — *xong code 2026-10-24, đã thử thật; chi tiết ở "20.3 — đã cài" dưới đây*: `edit` (diff trước/sau, `before_json`) và `undo`; cần spike 3 (`messages.editMessage`). 4. **20.4** — *xong code 2026-10-24, đã thử thật; chi tiết ở "20.4 — đã cài" dưới đây*: `repost` (đăng lại ở cuối rồi xoá bản cũ, `new_msg_id`); điều kiện của 20b. 5. **20.5** — *xong code 2026-10-25, đã thử thật; chi tiết ở "20.5 — đã cài" dưới đây*: `edit --mirror` theo `msg_map` (`07` mục 11.4, kể cả lượt sửa bù link tiến của 19c3). **Khác với đề xuất ở `07` mục 6** (không đụng D1–D10): 1. **`op_items.unit_id`** (cột thêm): id tin đầu của đơn vị, để một lô luôn cắt giữa các đơn vị (luật 4) mà không phải đoán album từ `grouped_id` lúc đọc lại. 2. **Plan không đếm "tin bị loại"**: khi filter được đẩy xuống server (một hashtag, một loại media), tin không khớp không bao giờ tới `Matcher`, nên số "bị loại" sẽ thiếu. Plan chỉ nói điều nó biết chắc: số tin được chọn. 3. **Filter rỗng cần `--all`** (hoặc một câu hỏi ở terminal): `07` không nói; một lệnh `delete` quên filter là cách dễ nhất để xoá cả kênh, và `--expect` chỉ chặn được khi người viết script biết con số. 4. **`--resume O` vừa áp một plan đã lưu vừa làm tiếp một thao tác dở**; không có lệnh `delete` riêng cho từng việc. Plan chưa từng áp cần xác nhận như bình thường, thao tác đã bắt đầu thì không hỏi lại (đã xác nhận khi bắt đầu). Một xác nhận sai (gõ khác số, `--expect` lệch) **huỷ** plan (`cancelled`) thay vì để lại. 5. **Lô xoá** tối đa 100 id nhưng luôn nguyên đơn vị: 99 tin lẻ rồi một album 3 tin thành hai lô (99 và 3), không phải một lô 102. 6. **`pending` quay về `planned` ngay khi Telegram từ chối rõ ràng** (FloodWait, mất quyền, `Interrupted` trong lúc chờ) vì lúc đó chắc chắn chưa xoá gì; chỉ `Transient` và kill để `pending` lại cho lần chạy sau đọc kênh mà phân xử. Xoá một id đã mất không phải lỗi nên lặp lại một lời gọi là an toàn. 7. **`daily_cap` không đếm `delete`** (`Limiter.sent_total`): xoá không phải đăng. Làn `delete` vẫn có delay AIMD và ngân sách tự học riêng như mọi làn ghi — chưa có số liệu thật (spike 2: tốc độ xoá và FloodWait khi xoá hàng nghìn tin). **Đã thử trên Telegram thật (2026-10-23, kênh `mediacenter` riêng tư của người dùng, tin thử có hashtag duy nhất, đã dọn hết)**: plan không xác nhận (mã 2, không xoá gì); `--expect` sai (mã 2, plan huỷ); `--yes --expect 12` xoá đúng 12 tin gồm 1 album, hai tin đối chứng và 46 tin sẵn có còn nguyên; một tin bị sửa sau plan được để nguyên (`changed`); `history`/`history O3`; một kênh test 133 tin (~19 GB chuyển tiếp): `stop` từ terminal khác dừng đúng sau lô 100 tin, `--resume` xoá nốt 33 tin (7 album, không cắt album). Còn chưa thử: kill cứng (`kill -9`) giữa lô, và spike 2 (tốc độ xoá, FloodWait khi xoá hàng nghìn tin; 133 tin xoá không gặp flood nào). Một thiếu sót lộ ra khi thử: `OpRunner` không lưu trạng thái limiter sau mỗi lô nên số tin đã xoá của làn `delete` không được nhớ giữa các lần chạy — đã sửa (`save_limiter_state` sau mỗi lô), có test. Tiêu chí hoàn thành của cả Phase 20 vẫn ở bảng đầu file. **20.2 — đã cài (2026-10-23)** — không đổi D1–D10; các điểm khác bản đề xuất ở `07` mục 6.3 hoặc chưa nói trong đó: 1. **Backup đúng các id của plan, không chạy lại filter.** `BackupWriter.run(..., only_ids=)` đọc theo id (`planner.failed_units`) rồi xuất từng đơn vị như một backup thường; id đã có trong `messages.jsonl` được bỏ qua (`backupdir.recorded_ids`, đúng tập hợp chứ không theo con trỏ `last_id`, vì một tin sửa sau plan có thể nằm dưới con trỏ), id đã mất tính `gone`. Hệ quả: `last_id` đổi từ "id ở dòng cuối" thành **id lớn nhất** (file backup thường vẫn tăng dần nên không đổi gì), vì lưới an toàn có thể nối một id thấp hơn dòng cuối. 2. **Thứ tự: plan → gõ lại số tin → backup → xoá.** Backup chạy sau xác nhận và **trước** `begin_op` (`engine/ops.py::begin_op_backup`/`settle_op_backup`, `cli/commands/delete.py::back_up`); chưa xong (dừng, lỗi, FloodWait) thì plan vẫn `planned`, chưa xoá gì, lệnh thoát mã 1 (hoặc mã của lỗi) kèm cách làm tiếp. `--resume O --yes --expect N` làm tiếp **cả backup lẫn xoá**: thư mục backup và cờ `backup_done` được nhớ trong `ops.options_json` (`Op.backup_dir`, `Op.backup_done`, `Store.set_op_options`), nên không cần gõ lại `--backup-to` và một backup đã xong không làm lại. Plan đã bắt đầu xoá (`running`/`stopped`/...) thì không hỏi lại backup. 3. **Hỏi hay không.** Có terminal và không `--yes`: hỏi Có/Không "Backup N tin này trước khi xoá?" (mặc định Có), rồi "Lưu vào `/safety/O`?" (Không → hỏi thư mục). Không terminal hoặc có `--yes`: chỉ backup khi có `--backup-to`. `--no-backup` bỏ câu hỏi; `--backup-to` cùng `--no-backup` mã 2. Một thư mục đã có backup của chính kênh đó với **cùng filter** thì backup nối vào (`begin_backup`), khác filter thì `FiltersChanged` — mặc định mỗi plan có thư mục riêng nên không đụng nhau. 4. **D3 cho bước backup.** Kênh `noforwards`: `--yes-i-administer-this-channel` (cờ mới của `delete`), hoặc ở terminal một câu Có/Không (tài khoản chắc chắn là admin vì plan đã đòi quyền đó); không terminal mà thiếu cờ → mã 2, chưa xoá gì. Không backup thì không cần. 5. **`status` biết thao tác** (`engine/status.py::OpStatusReport`/`build_op_report`/`op_estimate`, `cli/commands/status.py::_op_text`/`_op_record`): đang chạy thì ưu tiên run, rồi backup, rồi thao tác; lúc nghỉ thì cái có hoạt động cuối cùng gần nhất (`ended_at`/`updated_at`; trước đây so `started_at`, mà backup lưới an toàn bắt đầu **sau** plan nên sẽ thắng thao tác xoá). Khác backup, thao tác có tổng ngay từ đầu (plan) nên có phần trăm và ETA. `history O` và `status --json` cho thêm thư mục backup. 6. **Menu**: mục "Xoá tin trong kênh của mình…" (`ui/menu/screens/delete.py` — cùng `DeleteFlow`, nên cùng câu hỏi và cùng luật 11), rồi `ui/menu/op_screen.py::OpScreen` (một `TaskScreen` hai chặng: backup bằng `BackupTuiReporter`, xoá bằng `OpTuiReporter`; `p`/`r`/`q` tác động lên chặng đang chạy, `q` lúc backup để plan nguyên). Phím `d` ở "Khám phá" mở wizard đó với kênh và filter đã chọn sẵn (filter rỗng bị từ chối như ở dòng lệnh). Badge "đang chạy ở nơi khác" xét thêm `active_op` (`Screen.op_id`, `MenuApp.own_op_id`). 7. **Đã thử trên Telegram thật (2026-10-24, kênh `mediacenter` riêng tư của người dùng, tin thử có hashtag duy nhất, đã dọn về đúng 46 tin)**: plan + `--backup-to` không xác nhận (mã 2, chưa có thư mục); `--resume --yes --expect 11 --backup-to`: backup đủ 11 tin (album giữ nguyên nhóm, 2 file 3 MB) rồi mới xoá, `history O`/`status`/`status --json` đúng; không cờ thì không có thư mục `safety`; `restore` từ chính bản backup vào kênh mới dựng lại đủ 11 tin (1 album, 6 MB); `tgmirror stop` giữa lúc tải file 40 MB: mã 1, backup 1/4, kênh còn đủ, plan `planned`; `--resume` nối tiếp (chỉ tải 3 tin còn lại, qua một FloodWait 4 s) rồi xoá; `kill` cứng giữa lúc tải: `--resume` bị từ chối "backup đang được tiến trình khác chạy" cho tới khi dùng `--force-takeover` (như `backup`/`clone`), rồi nối tiếp đúng; D3 trên kênh bật «Restrict saving content»: không cờ mã 2 và chưa tải gì, `--resume` không cờ vẫn từ chối, có `--yes-i-administer-this-channel` thì backup + xoá; menu ("Xoá tin…" với thư mục mặc định, phím `d` ở Khám phá) do người dùng thử, đúng. **Phát hiện**: (a) tìm kiếm hashtag phía server của Telegram chậm lập chỉ mục tin vừa đăng nên `delete` có pushdown báo "không chọn tin nào" (chọn thiếu, không bao giờ thừa; `--no-pushdown` đọc đủ) — chưa xử lý, chỉ ghi; (b) đã sửa: `--backup-to` bị quên khi plan chỉ được lưu, và dòng gợi ý "tgmirror backup ..." thừa sau backup bị dừng; (c) `inspect` dùng chỉ mục cục bộ nên không thấy tin đã xoá cho tới khi `--refresh` (đúng như thiết kế). Chưa thử: spike 2 (tốc độ xoá hàng nghìn tin); `repost --delete-original` (20.4) sẽ dùng lại `begin_op_backup`; chưa có `Backup` → `O` ngược lại trong `history` (chỉ `O` thấy thư mục). **Test**: `tests/integration/test_op_backup.py` (backup đúng id của plan, tin sửa sau plan, album, làm lại không ghi trùng, tin đã mất, dừng giữa chừng, kênh `noforwards`), `tests/unit/test_cli_delete_backup.py` (cờ, câu hỏi, lỗi giữa backup giữ plan, `--resume` làm tiếp, D3, `history`/`status`), `tests/unit/test_menu_delete.py` (wizard, `OpScreen`, phím `d`, badge), `test_backupdir.py` (`recorded_ids`, `last_id` lớn nhất), `test_store_ops.py` (`set_op_options`), `test_status.py` (`op_estimate`). **20.3 — đã cài (2026-10-24)** — không đổi D1–D10: 1. **Gateway**: `rewrite_messages(chat, ids, policy) -> list[Rewrite(id, before, after, lossless)]` (chỉ đọc; `before`/`after` là văn bản dạng HTML như backup lưu, đi qua `FloodGuard.read`, làn `history`) và `edit_message(chat, id, text) -> bool` (`False` = Telegram nói tin đã đọc đúng thế; `MESSAGE_AUTHOR_REQUIRED`/`MESSAGE_EDIT_TIME_EXPIRED`/`MESSAGE_EMPTY`/`MESSAGE_ID_INVALID` là `PerMessage`). Làn limiter mới `edit` (`core/limiter.py::EDIT`, cùng loại với `delete`: có AIMD và ngân sách riêng, không tính vào `daily_cap`). 2. **Plan** (`engine/ops.py::plan_edit`): quét như `delete`, rồi cứ 100 tin hỏi `rewrite_messages` với `CaptionPolicy(ops=transform.caption, text_too=...)`; **chỉ tin có `after != before` được đóng băng**, kèm `{"before", "after"}` trong `op_items.before_json`. Tin được chọn mà transform không đổi gì thì chỉ đếm (`unchanged`); tin có định dạng HTML không chứa được (spoiler, ...) hoặc không đọc lại y nguyên thì đếm `lossy` và **không bao giờ sửa**, vì `undo` không trả lại nguyên vẹn được (hashtag, mention, URL trần do Telegram tự nhận ra nên không tính). Một văn bản mà các thao tác sẽ làm rỗng được để nguyên. Plan không có tin nào đổi thì không tạo dòng nào. 3. **Áp dụng** (`OpRunner`, nhánh `edit`/`undo`): mỗi lô 10 tin; **đọc lại văn bản hiện tại** của lô, chỉ sửa tin còn đọc đúng `before` của plan; tin đã đọc `after` thì coi là xong, tin đọc khác cả hai là đã bị người khác sửa → để nguyên (`changed`), tin mất → `gone`. Mỗi lần sửa ghi `pending` trước, `done` sau; lỗi riêng một tin (`PerMessage`) chỉ làm tin đó `failed` kèm lý do; FloodWait/mất quyền trả tin về `planned`. Reconcile sau kill (`_settle_edits`): đọc văn bản, `after` → xong, `before` → làm lại, khác → để nguyên. 4. **`undo`**: một thao tác `undo` riêng (`ops.kind='undo'`, `options_json.undo_of`) có item là các tin `done` của lần sửa với hai văn bản đảo chiều, nên dùng đúng vòng áp dụng trên (và cũng chỉ trả lại tin còn đọc đúng bản đã sửa). Mỗi lần sửa chỉ undo một lần (`UndoError`: `already`, `never_applied`, `not_an_edit`, `nothing`). Có plan, có gõ lại số tin / `--yes --expect N`, `--resume O` như `delete`. 5. **CLI**: `tgmirror edit [SRC] --transform FILE` (hoặc `--selection` có `transform:`) và `tgmirror undo [O]`; chung `DeleteFlow` (lớp con `EditFlow`/`UndoFlow`, câu chữ `edit.*`/`undo.*` dựng từ một khuôn chung trong `ui/messages.py`). **Không có câu hỏi backup**: bản gốc nằm trong plan, `undo` là đường lui. Transform có `topics`, `reply: keep`, `forward_header: keep` hay `links: rewrite` bị từ chối (mã 2): đó là việc của sao chép / `repost` / 20.5; thiếu thao tác `caption` cũng mã 2. `--resume` kiểm loại thao tác (`edit --resume` một plan `delete` thì chỉ sang đúng lệnh). `history`/`status` nói `edit`/`undo` bằng từ của nó. 6. **Chưa làm** (mục menu "Sửa chữ của tin…" đã có từ 2026-10-24): sửa theo `msg_map` (`--mirror`, 20.5, kể cả bù link tiến); sửa kênh có hàng nghìn tin chưa đo (spike). Người dùng xem trên app (2026-10-24): tin đã sửa **có nhãn "đã sửa"**, **không có thông báo** cho người theo dõi. 7. **Đã thử trên Telegram thật (2026-10-24, kênh `mediacenter` riêng tư của người dùng và kênh test cũ `-1004414908395`, tin thử có hashtag duy nhất)**: plan không xác nhận (mã 2, kênh nguyên vẹn, diff đúng: 8 tin đổi, 4 giữ nguyên, 1 tin spoiler không bao giờ sửa); `--expect` sai (mã 2, plan huỷ); sửa 8/8 tin gồm text, bold, link, caption album (chỉ tin mang caption) và caption document — định dạng giữ nguyên, tin đối chứng và tin spoiler không bị đụng; `undo` trả lại **y hệt** văn bản và entity gốc (bold, link, hashtag), `undo` lần hai bị từ chối; transform có `topics` bị từ chối (mã 2); một tin bị người khác sửa tay giữa plan và áp dụng thì để nguyên (7/8) và `undo` sau đó cũng không đụng nó; kill cứng giữa lúc sửa rồi `--resume --force-takeover` sửa nốt đủ 8 tin; **spike 3**: tin sao chép bằng forward bỏ tác giả (`clone`) sửa được như tin thường, còn tin forward **giữ header** thì Telegram trả `MESSAGE_ID_INVALID` — lệnh ghi `failed` từng tin kèm lý do (xem `history O`) và không dừng. **Phát hiện và đã sửa**: một thao tác bị kill để lại dòng `running`, `--resume` (kể cả `--force-takeover`) bị từ chối "cannot be taken up" — lỗi có từ 20.1 (kill cứng chưa từng được thử với `delete`); `Store.start_op` giờ nhận lại một dòng `running` có heartbeat đã cũ, hoặc đang tươi nếu có `--force-takeover` (không có thì `OpBusy`, như `backup`/`clone`). `history O` giờ liệt kê (tối đa 10) tin `failed` kèm lý do. **20.4 — đã cài (2026-10-24)** — không đổi D1–D10: 1. **Quyết định của người dùng (2026-10-24): file id của tin mới phải KHÁC bản gốc**, nên `repost` là **tải xuống rồi tải lên lại** (chiến lược B, `Prepared` + `send_prepared`), không phải forward hay gửi theo tham chiếu. (Thăm dò trước đó trên Telegram thật: forward bỏ tác giả *trong cùng kênh* biến một tin forward thành tin của kênh và cờ `silent` chạy, nhưng giữ **nguyên** document id — vì vậy bị loại.) Hệ quả: là một lần tải xuống nên **D3 áp như backup**: kênh `noforwards` cần `--yes-i-administer-this-channel` (hoặc câu Có/Không ở terminal), kiểm ở `engine/ops.py::begin_op` (không bỏ qua được) cho mọi lần bắt đầu/tiếp tục. 2. **Plan** = `plan_delete` với `kind=REPOST` (`plan_repost`): cùng danh sách đóng băng nguyên đơn vị, `options_json` ghi `delete_original` và `silent` (mặc định im lặng — đăng lại hàng loạt trên kênh sống là một trận thông báo; `--notify` bật lại), `op_items.before_json` ghi topic của tin. In thẳng cái giá phải trả: tin mới mất lượt xem, reaction, bình luận và ngày gốc; link/reply tới id cũ hỏng; poll/game/hoá đơn không đăng lại được nên được để nguyên (và không bao giờ bị xoá). 3. **Áp dụng** (`OpRunner._repost_batch`, lô 10 tin nguyên đơn vị): với mỗi đơn vị — đọc lại + xét lại filter (đổi thì để nguyên) → `reupload.plan_unit` (poll/game bỏ qua) → tải xuống (`reader.prepare`, vào `tmp_dir`) → ghi **`pending`** kèm `{"topic", "tail"}` (id tin cuối của kênh *trước khi gửi*) → `send_prepared(..., topic=, silent=)` → ghi **`reposted`** (có bản mới, `new_msg_id` đã lưu; không `--delete-original` thì ghi thẳng `done`) → xoá file tạm. Với `--delete-original`, **cuối lô** mới xoá một lượt các bản gốc đã có bản mới rồi ghi `done`; **không bao giờ xoá một tin chưa có bản mới**. Sau mỗi đơn vị, `_same_file_ids` đọc lại bản mới và đếm số tin vẫn mang file id cũ (Telegram dùng lại file có nội dung trùng): báo `same_file` (dòng kết quả + `stats.same_file`), không giấu. 4. **Reconcile sau kill** (`_repost_settle`): trước hết xử các `reposted` (xoá nốt bản gốc còn lại, hoặc đóng `done`); rồi với `pending` thì đọc đuôi kênh từ `tail` và xét bằng `engine/reconcile.judge` (số tin, loại media, cấu trúc album): khớp → ghi bản mới là `reposted`/`done`; không có gì mới → `planned` (đăng lại); có gì đó không khớp → **để nguyên** (`skipped`, `ambiguous`; không đăng thêm, không xoá), vì với `repost` thà thiếu hơn là trùng và mất. Mỗi đơn vị được ghi `pending` riêng nên mỗi lần chỉ có tối đa một đơn vị cần xét. 5. **Gateway**: `send_prepared(..., silent=)` (Telethon: `ContextVar` đọc ở các lời gọi `send_file`/`send_message`/`SendMultiMediaRequest`, để cờ khỏi phải đi qua mọi hàm giữa chừng); `FloodGuard.read("last_message_id")` ở làn `history`. Lô gửi đi qua làn `send` của kênh (tính vào `daily_cap`, khác `delete`/`edit`), xoá qua làn `delete`. 6. **CLI** `tgmirror repost [SRC] [--delete-original] [--notify] [--backup-to/--no-backup] [--yes-i-administer-this-channel]` (`cli/commands/repost.py`, `RepostFlow` là `DeleteFlow` với plan khác và câu chữ `repost.*`); hỏi backup (lưới an toàn của 20.2) **chỉ khi** có `--delete-original`; `--resume` không đổi được `--delete-original`. `history`/`status` nói `repost` bằng từ của nó. 7. **Chưa làm**: tải song song/tải trước (`Window`/`Pipeline` của clone — hiện mỗi đơn vị tải rồi tải lên tuần tự); nối lại reply *giữa* các tin cùng đăng lại (`reply: keep`) — việc của 20b; mục menu. 8. **Đã thử trên Telegram thật (2026-10-24, kênh `mediacenter` riêng tư, kênh test cũ bật Restrict saving content và forum «Mediacenter»; tin thử có hashtag duy nhất, đã dọn về đúng 46 tin)**: plan không xác nhận (mã 2, kênh nguyên vẹn, plan nói rõ cái giá); đăng lại text, tin forward giữ header, ảnh, document, album và poll: **mọi bản mới `silent`, file id KHÁC bản gốc ở ảnh/document/album** (đã đọc lại `Photo.id`/`Document.id`), tin forward thành tin của kênh, album nguyên, poll được để nguyên; `--delete-original --backup-to`: backup đủ 11 tin trước, rồi đăng, rồi xoá bản gốc (poll còn nguyên); `--notify`: bản mới `silent=False` (còn mặc định thì `silent=True`) — đọc lại từ Telegram; **người dùng không thấy được thông báo bằng chính tài khoản đã đăng** (Telegram không báo tin của chính mình), nên việc "người theo dõi nhận hay không" chỉ có thể thấy bằng một tài khoản phụ hoặc bot, chưa kiểm; D3 trên kênh Restrict saving content: không cờ mã 2 và chưa tải gì, có `--yes-i-administer-this-channel` thì chạy (5/5, file id khác); forum: tin ở topic 2 ở lại topic 2, tin General ở lại General; kill cứng giữa lúc đăng 4 file 40 MB với `--delete-original` rồi `--resume --force-takeover`: đúng 4 bản mới, 4 bản gốc bị xoá, không trùng (các bản đã đăng được xoá nốt gốc mà không đăng lại); `tgmirror stop` giữa chừng rồi `--resume`: không trùng. **Phát hiện và đã sửa**: (a) dòng kết quả gọi poll bị bỏ qua là "đã đổi từ lúc lập kế hoạch" — giờ có đếm riêng `unsupported`; (b) `stop` rơi đúng lúc kiểm tra file id sau khi đã gửi nên bản mới có mà mục còn `pending` (resume vẫn xử đúng bằng đuôi kênh, nhưng giờ ghi `reposted` ngay sau khi gửi, trước mọi bước có thể bị ngắt). **Quan sát về file id**: Telegram chia sẻ id giữa các lần tải lên có cùng nội dung (ảnh/album tạo từ cùng bytes ra cùng id ở các lần đăng lại khác nhau), nhưng id luôn khác id của tin gốc trong các ca thử; nếu một ca nào đó trùng thì lệnh báo `same_file` chứ không giấu. **20.5 — đã cài (2026-10-25)** — không đổi D1–D10, không migration: 1. **`tgmirror edit --mirror R --transform FILE`**: `R` là một lần chạy bất kỳ của cặp (`history`); lệnh sửa **ở kênh đích của cặp**, chỉ trên **các bản sao cặp đó đã đăng** (`Store.mirror_copies`: mọi dòng `done`/`skipped` có `dst_msg_id` của `msg_map`) — tin khác trong kênh đích (của người khác, của lần clone khác) không bao giờ được chọn dù filter nói gì (`plan_edit(scope=MirrorScope(copies, options))`). Không có filter thì không cần `--all` (phạm vi đã là các bản sao); có filter (`--hashtag`...) thì áp lên chính các bản sao đó. Mọi thứ còn lại là `edit` của 20.3: plan có diff, gõ lại số tin, đọc lại từng tin, `undo`. `--mirror` không đi cùng `SRC` hay `--resume` (plan đã giữ bản trước/sau), `options_json` ghi `mirror` và `run`. 2. **`links: rewrite` giờ dùng được ở đây** (và chỉ ở đây; không có `--mirror` thì `edit` vẫn từ chối nó): đó chính là **lượt sửa bù link tiến** mà 19c3 để lại. Bảng đổi là `msg_map` của cặp (nguồn → đích, qua `LinkRewrite.mapping`, giờ nhận cả `Mapping` vì một cặp có thể có hàng chục nghìn tin), tiền tố là link của kênh đích (`t.me/` hoặc `t.me/c/`), và `LinkRewrite.names` (trường mới) nói các link cần đổi là **vào kênh nguồn** (username hiện tại của nguồn nếu còn đọc được, và số của nó), vì tin đang sửa nằm ở kênh đích. Link tới tin không có trong bảng, hoặc vào chat khác, giữ nguyên. Chỉ `links: rewrite` (không có thao tác `caption`) cũng đủ để chạy. 3. **Đã thử trên Telegram thật (2026-10-25, nguồn là kênh `mediacenter` riêng tư `t.me/c//`, đích là kênh test cũ được công khai tạm với một username rồi trả về riêng tư; tin thử có hashtag duy nhất, đã dọn về đúng 46 tin)**: `clone --rewrite-links` 5 tin có link (A, B và C có link lùi, C còn một hyperlink tiến, D link tới tin không clone và tới chat khác): link lùi trỏ về bản sao kiểu `t.me//`, link tiến còn trỏ về nguồn, lệnh đếm đúng link còn lại; `edit --mirror R` (file chỉ có `links: rewrite`): plan chỉ có tin C đổi, 4 tin còn lại "để nguyên", sửa xong **hyperlink tiến trỏ đúng bản sao của E** (người dùng bấm thử trong app: mở đúng tin), chữ và định dạng giữ nguyên, link tới tin không clone và tới chat khác không đổi; một tin đăng tay vào kênh đích ngoài cặp (cùng có link tới nguồn) **không bị đụng**; `undo` trả lại đúng; `--mirror` + `remove_hashtags` chỉ sửa 5 bản sao của cặp, tin ngoài cặp giữ nguyên hashtag; `--mirror` kèm `SRC`, run không có, `links: rewrite` không `--mirror`: đều mã 2. **Quan sát**: một link trần (`MessageEntityUrl`) trong tin bị sửa trở thành hyperlink (`TextUrl`) cùng địa chỉ — chữ hiển thị y hệt, nhưng entity đổi loại (HTML không phân biệt hai loại); `undo` cũng trả về dạng hyperlink. Số "bản sao" của cặp cộng cả các dòng `msg_map` của những lần chạy cũ mà tin đích đã bị xoá (vô hại: không có tin để chọn). **Chưa làm**: đếm riêng "link vẫn chưa đổi được" trong plan; chọn cặp bằng `SRC DST` thay vì số lần chạy; mục menu. **Test (20.5)**: `tests/unit/test_cli_edit.py` (link của bản sao trỏ về bản sao, tin ngoài cặp và link vào chat khác/tin chưa sao chép giữ nguyên, `undo`, `--mirror` + thao tác `caption`, từ chối khi thiếu/dư tham số), `tests/integration/test_op_edit.py` (phạm vi), `tests/unit/test_telethon_edit.py` (`LinkRewrite.names` trên message Telethon). **Test (20.4)**: `tests/integration/test_op_repost.py` (bản mới ở cuối, file id mới, im lặng, tin forward thành tin của kênh, album nguyên, `delete_original` đúng thứ tự, poll không bị xoá, tin đã đổi, topic, D3, kill giữa lúc gửi / sau khi gửi / sau khi đăng trước khi xoá, đuôi kênh không khớp, FloodWait), `tests/unit/test_cli_repost.py` (xác nhận, `--delete-original` + backup trước, hỏi backup chỉ khi xoá, D3, `--resume`), `test_telethon_reupload.py` (`silent`). **Test (20.3)**: `tests/integration/test_op_edit.py` (plan chỉ đóng băng tin đổi, áp dụng, đã bị sửa/mất, `PerMessage`, lossy, cắt kết nối giữa chừng, FloodWait, stop, undo một lần), `tests/unit/test_cli_edit.py` (xác nhận, transform bị từ chối, `--resume` đúng loại, undo, `history`/`status`), `tests/unit/test_telethon_edit.py` (`_rewrite_message` trên message Telethon thật, `lossless`, `edit_message`, ánh xạ lỗi), `test_architecture.py` (`guard.read`). **Test (20.1)**: `tests/integration/test_ops.py` (plan, áp dụng, album không cắt, tin đã đổi/đã mất, kill/mất kết nối giữa lô, FloodWait, mất quyền, stop/pause, một thao tác mỗi kênh), `tests/unit/test_store_ops.py` (migration 8, trạng thái item), `tests/unit/test_cli_delete.py` (xác nhận, `--expect`, `--all`, `--resume`, `history`, `stop`), `test_limiter.py` (làn `delete`), `test_architecture.py` (`engine/ops.py` chỉ chạm gateway qua `FloodGuard`). ### Phase 20b — ghi chú (2026-10-24; xong code và đã thử trên Telegram thật cùng ngày) Theo yêu cầu người dùng ("làm hết luôn lát này và test một lượt"). Không đổi D1–D10, không migration (`ops.kind` là chuỗi tự do). Ngữ nghĩa đúng như `07` mục 11.3 đã duyệt; chỗ khác hoặc chưa nói ở đó: 1. **`tgmirror topics` thành một nhóm lệnh** (`cli/commands/topics.py::topics_app`, `TopicsGroup`): `list` (mặc định — `tgmirror topics FORUM` vẫn liệt kê như trước; `TopicsGroup.parse_args` chèn `list` vào trước khi nhóm đọc dòng lệnh nên `--` vẫn tới được lệnh con), `split`, `merge`, `move --resume`, `delete`, `rename`, `close`, `reopen`. 2. **Loại thao tác mới `move`** (`OpKind.MOVE`; `OpKind.posts_again` gom `repost` và `move` ở mọi chỗ cần D3 / tải lên lại): là `repost --delete-original` mà **đích là một topic khác** — mỗi đơn vị được tải xuống rồi tải lên lại vào topic đích (id mới, file id mới, im lặng; `--notify` bật thông báo), ghi `new_msg_id`, **chỉ sau đó** xoá bản gốc, `pending` ghi trước kèm đuôi kênh để reconcile, nguyên đơn vị (không cắt album). Mỗi item ghi `before_json {"dest": , "dest_id": }`; topic đích được tìm **theo tên** lúc áp dụng (`OpRunner._topic_titled`, đọc `list_topics` một lần), chưa có thì tạo — **kế hoạch không tạo gì**, nên chưa xác nhận thì Telegram nguyên vẹn (luật 11). Ghi chú `pending` giữ `dest`, nên một đơn vị làm lại sau kill vẫn đi đúng topic. Tin chuyển vào General được đăng không kèm topic. 3. **Thứ tự**: một lần chia đi qua từng đơn vị của topic nguồn theo id tăng dần, nên mỗi topic đích nhận theo đúng thứ tự gốc; một lần gộp đặt `unit_id = vị trí topic × 10¹² + id đầu` (`engine/topicops.py::TOPIC_ORDER`) để `op_units` (sắp theo `unit_id`) đi hết topic này rồi mới sang topic kế, theo **thứ tự gõ**. Tin chuyển luôn nằm sau mọi tin sẵn có của topic đích; plan nói điều đó ("đã có tin: tin chuyển sang nối ở cuối") khi đích đã có tin. Plan đọc cả forum một lần (lọc topic phía máy, như `--topic` ở nơi khác). 4. **Reply giữa các tin cùng được chuyển được nối lại** (`OpRunner._reply_to`, `Store.op_new_ids`): một tin trả lời tin khác mà tin đó đã có bản mới trong chính thao tác này thì bản mới trả lời bản mới. Áp dụng cả cho `repost` (đó là phần "nối lại reply" mà 20.4 để lại). Tin trả lời một tin không nằm trong kế hoạch thì mất reply (không giữ được qua topic). 5. **Xoá topic** chỉ khi rỗng (`OpRunner._drop_topics`, chạy khi mọi item xong): đọc lại topic (`topic_message_ids`, bỏ tin dịch vụ); còn tin (đăng vào giữa chừng, hoặc poll/game không chuyển được) thì **giữ topic**, đếm `topics_kept` và báo; General không bao giờ bị xoá (gộp *vào* General được, gộp General vào topic khác bị từ chối). `stats` có `topics_dropped`/`topics_kept` (`history O` có dòng «Topic: …»). Sau kill ngay trước khi xoá topic thì `--resume` xoá nốt, không đăng lại. 6. **`topics delete`** là `delete` thường (kind `delete`, `options_json.drop_topics`) trên các tin của một topic, rồi xoá topic: có lưới an toàn backup, gõ lại số tin, tiếp bằng `tgmirror delete --resume O`. Topic rỗng thì chỉ hỏi Có/Không (hoặc `--yes`) rồi xoá vỏ topic. 7. **`rename`/`close`/`reopen`** không đụng tin nào nên không phải plan: một câu Có/Không ở terminal, `--yes` khi không có terminal (không có thì mã 2). Chúng đi qua `FloodGuard` (`engine/topicops.py::change_topic`, làn `edit`) nhưng không có dòng `ops`. General không đổi tên/đóng được bằng lệnh này. 8. **Gateway** thêm `edit_topic` (`messages.editForumTopic`; `TOPIC_NOT_MODIFIED` không phải lỗi), `delete_topic` (`messages.deleteTopicHistory` lặp tới khi `offset` về 0) và `topic_message_ids` (`iter_messages(reply_to=topic)`, bỏ tin dịch vụ); `TOPIC_ID_INVALID`/`TopicDeletedError` là `PerMessage`. Làn limiter: `edit_topic` → `edit`, `delete_topic` → `delete`, `topic_message_ids` → `history`. 9. **Chia chỉ nhận luật định tuyến** (`--transform` có `topics:` hoặc `--hashtag-to-topic` cùng `--topic-skip/--topic-regex/--topic-pick`): transform còn thao tác `caption`, `links` hay `forward_header` bị từ chối (đổi chữ là việc của `edit`); không có luật thì mã 2. `split` còn nhận cờ lọc và `--selection` (bổ sung cùng ngày: bộ lọc thu hẹp những tin của topic được xét, luật định tuyến quyết định chúng đi đâu). 10. **Đã thử trên Telegram thật (2026-10-24, forum «Mediacenter» `-1004422902694` của người dùng, 132 tin và 2 topic sẵn có không đụng tới; topic `t20b-A/B/C` và 9 tin thử do mình tạo, đã dọn về đúng 2 topic và 132 tin)**: `split` topic A theo luật hashtag `#t20bx` → `t20b-X`: plan không xác nhận (mã 2, forum nguyên), rồi `topics move --resume --yes --expect 3`: topic X được tạo, x1, x2, x3 **đúng thứ tự**, x3 vẫn **trả lời bản sao của x1**, A còn a1, a2; `merge B C --backup-to`: backup 2 tin trước, c1, c2 nối sau b1, b2, topic C bị xoá; `rename`/`close`/`reopen` (không `--yes` và không terminal → mã 2); `close General` bị từ chối; `topics delete` ba topic (một lần `--expect` sai → mã 2, chưa xoá gì; một lần dùng `delete --resume` cho plan đã lưu). **Phát hiện**: danh sách topic của Telegram (`getForumTopics`) **chậm vài giây** sau một thay đổi — ngay sau `close`, `list_topics` vẫn báo `closed: false` và sau `rename` có lúc còn tên cũ (dần đúng sau ít giây); vì vậy `rename`/`close`/`reopen` dùng đúng topic đã chọn thay vì đọc danh sách lần hai, và một lệnh gọi liền sau thay đổi có thể thấy trạng thái cũ. **Thử lần hai cùng ngày (cùng forum, topic `t20b-M1/M2`, đã dọn về đúng 2 topic và 132 tin)**: `merge` M1 ← M2 với 3 file 25 MB, một album 3 file và một poll; **kill cứng giữa lúc đăng lại file thứ hai** (các bản sao đã có, bản gốc chưa xoá) → `--resume` bị từ chối cho tới khi dùng `--force-takeover`, rồi làm xong: mỗi tin đúng **một** bản sao, không sót, thứ tự và album giữ nguyên, bản gốc bị xoá, poll ở lại nên **topic M2 được giữ** (báo «1 topic được giữ lại vì còn tin»); `split` vào **topic đã có tin** → tin chuyển nối sau tin sẵn có, tin không khớp luật ở lại; `topics delete` topic có cả poll xoá được cả topic. Chưa thử: kill cứng khi gộp nhiều nghìn tin. **Test (20b)**: `tests/unit/test_cli_topics_ops.py` (chia: chỉ lưu plan, thứ tự + topic mới, vào topic đã có tin, reply nối lại, `--expect` sai, cần luật và không đổi chữ, `--hashtag-to-topic`, D3, backup trước, `move --resume` đúng loại; gộp: nối lần lượt rồi xoá topic rỗng, topic còn tin được giữ, General, hai topic khác nhau, wizard; xoá topic và topic rỗng; đổi tên/đóng/mở lại, hỏi Có/Không, General), `tests/integration/test_op_move.py` (gửi bị cắt sau khi tạo topic → dùng lại đúng topic, gửi đã đi trước khi cắt → không đăng đôi, xoá topic sau cú cắt, tin đăng vào giữa chừng giữ topic, album chuyển nguyên), `tests/unit/test_telethon_gateway.py` (`edit_topic`, `delete_topic` lặp, lỗi topic không có), `tests/unit/test_cli_topics.py` (liệt kê vẫn chạy). `scripts/mutation_check.py` thêm 3 cơ chế (chạy tay). ### Phase 17 — ghi chú (2026-10-24; xong code và đã thử trên Telegram thật cùng ngày) Theo yêu cầu người dùng ("hoàn tất luôn phase 17, implement, unit test và test trên kênh thật"). Không đổi D1–D10 (D10 cho ghi/xoá tại chỗ khi có xác nhận; kênh đích là kênh của người dùng, thay đổi đi qua đúng plan → xác nhận → áp dụng của Phase 20). Không migration. Đề xuất ở `07` mục 6.5 ("một lệnh mỏng: tin nguồn đã đổi/xoá → plan edit/delete trên đích") được cài như sau; chỗ nào khác đề xuất thì ghi rõ. 1. **`tgmirror sync-changes [R]`** (`cli/commands/sync.py`, `engine/sync.py::plan_sync`): `R` là một lần chạy bất kỳ của cặp (mặc định: lần chạy mới nhất; ở terminal có nhiều cặp thì hỏi, như `run`). Lệnh đọc lại **nguồn theo id** cho mọi bản sao mà cặp đã đăng (`msg_map`, `Store.mirror_copy_rows`: dòng `done`, và dòng `skipped` có tin giữ chỗ), 100 id mỗi lời gọi qua `FloodGuard` (`FloodOwner.of_inspect`, làn đọc như `inspect`), rồi đóng băng **hai plan ở kênh đích** — hai thao tác `O` bình thường, nên `history`/`--resume`/`undo` dùng nguyên: - **`edit`** cho mỗi bản sao có chữ khác nguồn bây giờ. Chỉ xét tin nguồn có `edit_date` (chưa từng sửa thì bản sao không thể lệch vì nguồn); với tin đó, chữ mong đợi là `rewrite_messages(nguồn, policy của cặp)` (`engine/sync.py::policy_of_pair`: `caption`/`caption_text`/transform lưu trong `RunOptions`, cộng `LinkRewrite` nếu transform có `links: rewrite`) so với chữ hiện tại của bản sao (`rewrite_messages(đích, CaptionPolicy())`) — cả hai qua cùng một dạng HTML nên bằng nhau là bằng nhau. Bằng nhau → "đã khớp"; khác → tin được đóng băng kèm `{"before", "after"}` như `edit` của 20.3; định dạng HTML không chứa được (bên nào cũng vậy) → `lossy`, không bao giờ sửa; bản sao đã mất ở đích → đếm. Cặp có `topic_as_hashtag` thì **bỏ qua phần sửa** (bản sao mang hashtag topic mà không transform nào ở đây tái hiện được; có dòng báo). - **`delete`** cho mỗi bản sao mà tin nguồn **không còn** và bản sao vẫn còn ở đích (đọc lại đích để biết; bản sao đã mất thì chỉ đếm "đã mất sẵn"). Bản sao của một album nguồn đi chung một unit; xoá chỉ những tin nguồn đã mất, các tin còn lại của album không đụng. Mỗi item ghi `before_json {"src": }` và `options_json.sync_src`. Sổ `options_json` của cả hai plan ghi `sync_src`, `mirror`, `run` (edit thêm `transform`); `history O` có dòng «Đồng bộ: theo nguồn …, lần chạy R» (`Op.sync_src`/`Op.sync_run`). 2. **Không dùng chỉ mục metadata** (khác gợi ý ở `07` mục 6.5): chỉ mục là tiện ích dựng lại được, "không bao giờ là cơ sở của một lần ghi" (Phase 18b); các lần đọc ở đây đều sống. Cái giá là đọc `⌈bản sao / 100⌉` lời gọi cho mỗi lần chạy (60.000 bản sao ≈ 600 lời gọi, cỡ một lần `inspect`), nên phần này chạy tay chứ không tự động. 3. **Đọc không thấy ≠ đã xoá.** Hai lớp chặn: (a) `get_channel(nguồn)` phải đọc được, không thì cả lệnh lỗi và không lập plan nào (nguồn bị ra khỏi/đổi quyền không bao giờ thành "xoá hết"); (b) **áp dụng đọc lại nguồn** trước mỗi lô xoá (`OpRunner._back_at_source`): bản sao mà tin nguồn lại xuất hiện (hoặc item không ghi nguồn nào) thì giữ (`skipped`, lý do `changed`), vì chỉ một câu trả lời rỗng của Telegram mới nói "đã xoá". Cộng với cảnh báo trong plan khi ≥ 50% bản sao của cặp sắp bị xoá (có thể là tài khoản không còn xem được lịch sử nguồn). Xoá một bản sao có thể là xoá **bản duy nhất còn lại** của tin đó; plan nói thẳng điều này, và có lưới an toàn backup như `delete`. 4. **Một xác nhận cho cả hai plan** (luật 11): ở terminal gõ lại **tổng** (sửa + xoá; câu hỏi nói rõ hai con số), không terminal thì `--yes --expect N` với N là tổng; không có thì cả hai plan được giữ và lệnh in hai lệnh `edit --resume O …` / `delete --resume O …`. Sai số hoặc gõ khác → huỷ **cả hai** plan, chưa đổi gì. `--edits/--no-edits`, `--deletes/--no-deletes` bỏ bớt một nửa. Backup (`--backup-to DIR`/`--no-backup`, hỏi ở terminal; D3 với `--yes-i-administer-this-channel` nếu đích bật «Restrict saving content») là của **các bản sao sắp xoá** (`DeleteFlow.backup_plan(plan.delete)`), chạy sau xác nhận và trước mọi thay đổi. 5. **Thứ tự áp dụng**: backup (nếu có) → `edit` → `delete`. Phần xoá chỉ bắt đầu khi phần sửa kết thúc `done`; không thì lệnh thoát mã 1 và in cách làm tiếp cả hai (`edit --resume`, `delete --resume`). Mỗi phần dùng nguyên `OpRunner` của 20.1/20.3: đọc lại từng bản sao, tin bị người khác sửa giữa chừng thì để nguyên, `pending` ghi trước, reconcile sau kill. 6. **Không đồng bộ được**: media đã đổi (chỉ chữ), reaction, thứ tự, tin ghim; bản sao forward **giữ header** (Telegram không cho sửa: `failed` từng tin kèm lý do trong `history O`, như spike 3). Chưa có: tự động hoá/lên lịch (không có daemon), chạy khi nguồn đã mất hẳn (nguồn phải đọc được). **Bổ sung cùng ngày**: `--src`/`--dst` gọi cặp thay cho `R`, `--min-id`/`--max-id` thu hẹp vào các bản sao của tin nguồn trong một khoảng id (cờ lọc khác không có: tin nguồn đã mất không còn gì để lọc), và mục menu "Đồng bộ thay đổi của nguồn sang bản sao…". Đã thử thật: nguồn là **forum** (topic `t20c-S` → kênh không phải forum: cặp có `topic_as_hashtag`, plan báo bỏ qua phần sửa và vẫn xoá đúng bản sao của tin đã xoá). 7. **Đã thử trên Telegram thật (2026-10-24, nguồn `mediacenter` riêng tư `-1004379351926`, đích kênh test cũ `-1004414908395` bật «Restrict saving content»; 4 tin thử có hashtag `#sync17` do mình đăng, đã dọn về đúng 46 tin ở nguồn và 1 tin ở đích)**: `clone --hashtag #sync17 --no-pushdown` rồi sửa một tin và xoá một tin ở nguồn: `sync-changes` không xác nhận → mã 2, đúng hai plan (O58 sửa 1, O59 xoá 1; 34 tin nguồn đã xoá từ các lần thử trước mà bản sao cũng đã mất chỉ được đếm), đích nguyên; `edit --resume O58 …` và `delete --resume O59 …` áp đúng; chạy lại `sync-changes` → «Không có gì để đồng bộ» (không tạo plan); `undo O58` trả lại chữ cũ; sau đó `--yes --expect 5` (sai) → mã 2, huỷ cả hai plan, đích nguyên; `--yes --expect 2 --backup-to DIR` (đúng): dừng ở D3 vì đích bật «Restrict saving content» (chưa đổi gì), thêm `--yes-i-administer-this-channel` → backup 1 tin (đúng bản sao sắp xoá, `messages.jsonl`) rồi sửa 1 rồi xoá 1; `history O58` có dòng «Đồng bộ». **Phát hiện và đã sửa ngay**: cảnh báo «≥ 50% tin không còn ở nguồn» đếm cả các bản sao đã mất ở đích (92% trong lần thử đầu dù chỉ 1 bản sao sắp bị xoá) — giờ chỉ đếm bản sao **sắp bị xoá** (`SyncSummary.delete_share`). **Thử lần hai cùng ngày (cùng hai kênh, tin thử có hashtag `#tour17`, đã dọn về đúng 46 tin ở nguồn và 1 ở đích)**: `clone` rồi sửa một tin, xoá một tin chữ, xoá **2 trong 3 tin của một album** và một file 25 MB ở nguồn → plan đúng 1 sửa + 4 xoá (album chỉ mất bản sao của hai tin đã xoá, tin còn lại ở nguyên); **kill cứng giữa lúc tải file 25 MB của bước backup** → chưa xoá gì, `delete --resume O78 --force-takeover` backup nốt phần còn lại rồi xoá đúng 4 tin (backup đủ 4 bản ghi); `edit --mirror` bỏ hashtag rồi `undo` cả hai lần sửa trả lại đúng chữ. Chưa thử: nguồn là nhóm/forum (phần ops dùng chung đã thử ở 20.1–20.4). **Test (17)**: `tests/unit/test_cli_sync.py` (sửa ở nguồn → sửa bản sao; xoá ở nguồn → xoá bản sao; không xác nhận chỉ lưu hai plan và `edit/delete --resume` áp từng cái; `--expect` là tổng, sai/thiếu huỷ cả hai; gõ lại tổng; bỏ bớt `--edits`/`--deletes`; chạy lại không còn gì; **tin nguồn xuất hiện lại trước khi áp dụng thì bản sao không bị xoá**; bản sao bị sửa tay sau plan để nguyên; bản sao sửa tay mà nguồn chưa từng sửa không bị xét; transform của cặp áp lên chữ mới của nguồn; album chỉ mất bản sao của tin đã xoá; nguồn không đọc được → không lập plan; đích không phải admin → mã 4; backup đúng bản sao sắp xoá; định dạng không viết lại được; `history` có dòng đồng bộ; cặp `topic_as_hashtag` không sửa). Đã kiểm bằng đột biến thủ công: bỏ `_back_at_source` làm test «tin nguồn xuất hiện lại» fail; thay `_plan_edits` bằng không-làm-gì làm test sửa fail. ### Phase 21 — ghi chú (2026-10-18; xong code kể cả bốn mục làm sau; thử thật một phần 2026-10-23) - **Mô hình** (`engine/routing.py`, mới): `RouteRule`/`Routed`/mẫu tên/`TransformError` (định nghĩa ở đây, `engine/transform.py` re-export). `TopicRules` còn `rules`, `default`, `limit`, `strip`, `renames`, `hashtag_format`; `routes`/`auto_*`/`strip_tag` của 19b đã bỏ. Dạng chuẩn lưu trong `RunOptions.transform_json` là `route`; JSON 19b đã lưu vẫn nạp (dịch khi đọc), nên `run`/`retry` của cặp cũ không đổi. Chi tiết kỹ thuật: `01-kien-truc.md`, "Luật định tuyến `route`". - **Khác bản đề xuất ở `07` mục 11.2**: (1) `regex` với nguồn không phải `text` chỉ **lọc** ứng viên và cho nhóm, `{value}` vẫn là ứng viên nguyên vẹn (với `text` mỗi lần khớp là một ứng viên); (2) `from: text` bắt buộc có `regex`; (3) `limit` chỉ hợp lệ khi có tên có biến (như `auto: all` trước đây); (4) `strip` ghi `matched` (nhận cả `true`); (5) `when` kết hợp theo "một tin của unit thỏa" (như `album: any`); (6) luật `from: topic` đọc tên topic nguồn qua `list_topics` một lần mỗi lần chạy. - **Q3 (nhãn thành hashtag)**: `begin_run`/`plan_endpoints` không còn từ chối đích không phải forum (`DestinationNotForum`, `topics_need_forum` đã xóa); thêm cảnh báo `route_hashtags` và `InvalidOptions("route_needs_rewrite")` cho `--mode copy`. `inspect --plan` luôn giả định đích forum (không biết đích), nên số unit gửi lại của luật→hashtag không hiện ở đó. - **Phần còn lại, làm sau (2026-10-18, người dùng nêu 4 mục chưa làm)**: (1) cờ `--topic-skip`/`--topic-regex`/`--topic-pick`/`--topic-limit` (`pick` thêm vì ca 1 cần nó) tinh chỉnh luật `auto: all` — `TopicRules.with_auto_all(skip, pattern, pick, add)` và `layered(limit=)`, `cli/transform_options.py`; (2) `inspect --plan ... --dst-no-topics` (`PlanOptions.label_hashtag`, `Plan.hashtags`): đích không phải forum thì bảng kế hoạch là hashtag và các tin mang nhãn được tính là gửi lại; (3) bảng "topic đích": `Inspector` nhóm `route` (`inspect --by route`, tính theo **đơn vị**, album cùng một topic) và cột của màn Khám phá, nạp transform bằng phím `t` (`Explorer.set_rules`); (4) bước wizard `CloneFlow._pick_routing` ("Chia tin theo hashtag?", mặc định Không), đặt **trước** đích vì nó quyết định đích mới có là forum. Menu dùng chung `CloneFlow` nên có luôn. Hệ quả: một câu hỏi `confirm` mới trong wizard dịch chỗ các câu trả lời có kịch bản trong ~30 test wizard (đã sửa). Luật 7 vẫn giữ: cờ là tập cha — luật có `when`/`from: text`/mẫu tên chỉ trong file. Tiêu chí hoàn thành (hai ca thật + cùng file sang kênh thường) là việc của người dùng. - **Test**: `tests/unit/test_phase21_leftovers.py` (cờ, `--dst-no-topics`, `--by route`, `Explorer`, wizard), `test_menu_explore.py` (phím `t`). - **Test**: `tests/unit/test_routing.py` (mẫu, bộ lọc, hai ca, strip, đọc/từ chối luật, cú pháp tắt = cú pháp dài), `test_runner_topic_rules.py` (ca 1, ca 2, `from: topic`, `limit`, nhãn → hashtag), `test_preflight.py` (unit không khớp), `test_cli_transform.py`. ### Đã chốt (người dùng duyệt 2026-09-25) 1. **Phase 11, restore một backup có lời tuyên bố D3**: restore **hỏi lại lời tuyên bố** (cờ `--yes-i-administer-this-channel`, hoặc câu gõ nguyên văn khi tương tác), dù nội dung đã nằm trên đĩa, cho nhất quán "không bao giờ âm thầm"; `begin_run` **bỏ qua** bước đọc lại nguồn khi nguồn là thư mục backup (kênh gốc có thể đã mất — đó chính là lúc cần restore), thay vào đó đọc cờ `noforwards` và lời tuyên bố ghi trong `backup.json`. Đây là cách áp D3 cho một đường mới, không đổi nội dung D3. 2. **Phase 11 mở rộng "Mục tiêu" của `00-tong-quan.md`** (thêm backup/restore) — sửa khi phase bắt đầu, không sửa trước. 3. **Phase 11**: định dạng `messages.jsonl` + text dạng HTML của Telethon, như mô tả ở trên. 4. **Phase 13 gốc** (nội dung nay thuộc **Phase 14** sau khi tách, xem mục 5): package id winget `tamvcspk.tgmirror`; **có** phát hành lên PyPI thật (Trusted Publishing), không chỉ GitHub Release; kho APT/RPM **tự host trên GitHub Pages**, ký bằng GPG của người dùng (Cloudsmith không dùng). 5. **2026-09-26**: người dùng chọn làm **một lát cắt trước** thay vì cả Phase 13 gốc (CI + khung `release.yml` + đẩy ảnh Docker) — phần còn lại (PyInstaller/PyPI/winget/APT-RPM/AUR) tách thành **Phase 14** riêng, để phiên sau; đổi kênh ảnh container từ GHCR (kế hoạch gốc, mục 4 ở trên không nhắc lại GHCR nhưng "Từng kênh" đã ghi) sang **Docker Hub** (`docker.io/tamvo1808/tgmirror`) theo yêu cầu mở rộng phạm vi của người dùng — không dùng cả hai. Cần `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` (access token, không phải mật khẩu) làm secret của repo GitHub, người dùng tự thêm. Cùng lúc, người dùng thêm **Phase 15** (màn hình TUI full-screen cho backup/restore) vào lộ trình, và cả hai phase mới (14, 15) đẩy "Đồng bộ edit/delete" từ 14+ thành **16**. 6. **2026-09-27**: người dùng chốt cách đóng gói/nộp winget (Phase 14, chưa bắt đầu code): đóng gói **zip** `onedir` (không dựng installer `.exe`/`.msi` có ký, khớp với "Chỗ PyInstaller hay gãy" — binary Windows không ký), và **tự động hoá việc mở PR vào `microsoft/winget-pkgs` bằng GitHub Action `vedantmgoyal2009/winget-releaser`** thay vì tự viết bước `wingetcreate update --submit` trong `release.yml`. Cần một Personal Access Token (scope `public_repo`) của tài khoản GitHub người dùng, lưu làm secret `WINGET_PAT` của repo `tgmirror` — người dùng tự tạo và thêm trước khi bước này chạy được. Xem "Phase 14 — Phát hành đầy đủ". 7. **2026-09-27**: thêm **Phase 16 — Phát hành 0.1.1 chính thức** vào lộ trình (push tag `v0.1.1` thật, đóng tiêu chí bỏ ngỏ "chưa thử với tag thật" của Phase 13); "Đồng bộ edit/delete" dời số từ **16** thành **17**. Chưa push tag tại thời điểm ghi (repo chưa có tag nào, `pyproject.toml` vẫn `0.1.0`) — người dùng xác nhận **chỉ push khi đến lúc phát hành thật**, không phải ngay bây giờ; phase này coi là bỏ ngỏ cho tới khi đó dù đã có số trong lộ trình. 8. **2026-09-27 (Phase 15b)**: định dạng backup (mục 3) được **thêm** một trường tùy chọn cho tên file gốc của media (và tiêu đề/người trình bày của audio) để restore gửi lại đúng tên — tương thích ngược, `FORMAT_VERSION` giữ 1. Cùng ngày: **chặn hẳn hai tiến trình kết nối Telegram trên cùng session** (khóa file cấp hệ điều hành), và một cặp restore mất thư mục backup được **cập nhật đường dẫn** hoặc **chạy lại từ đầu** thay vì chỉ báo lỗi. Xem "Phase 15b". ## Việc cần xác minh sớm (spike, phase 0–1) 1. ~~Phiên bản Telethon cài đặt có tham số `drop_author` của `forward_messages` không?~~ **Xong 2026-09-19:** có. Telethon 1.45.0 `forward_messages(..., drop_author=, drop_media_captions=, as_album=)`. `pyproject.toml` đặt `telethon>=1.45` nên không cần fallback `ForwardMessagesRequest`. 2. ~~Forward một danh sách id có giữ nguyên album khi `drop_author=True` không?~~ **Xong 2026-09-20:** có, người dùng đã thử trên tài khoản thật (chưa đo riêng từng cỡ album). 3. `iter_messages(..., reverse=True, search=..., filter=...)` kết hợp `min_id` cho kết quả đúng thứ tự tăng dần? *(đọc mã Telethon 1.45: `min_id` thành `offset_id = min_id + 1`, `max_id` **loại trừ**; `search`/`filter` chuyển thành `messages.search` với `add_offset` âm, và `offset_date` trở thành `max_date` nên hỏng khi `reverse=True`, vì vậy ngày được đổi thành id bằng một lời gọi riêng. **Chưa thử trên Telegram thật**: chạy cùng một job với `--pushdown` và `--no-pushdown` rồi so số tin đã sao chép)* 4. Hành vi thực tế của quyền để xác định `can_post` và `is_admin` (broadcast, supergroup, group). **Phase 1** suy từ entity (`creator`, `admin_rights`, `banned_rights`, `default_banned_rights`, có xét `until_date`) thay vì `get_permissions`, vì gọi `get_permissions` cho từng dialog là một request mỗi kênh; đã khớp trên account thật với kênh broadcast, còn cần đối chiếu supergroup/group/forum trước khi tick. 5. Cách phát hiện `noforwards` đáng tin cậy (`Channel.noforwards`, và `Message.noforwards`). Phase 1 đọc `Channel.noforwards`/`Chat.noforwards` trong `channel_info`; `Message.noforwards` chưa dùng. 6. Số tin/lời gọi và delay nào chạy êm trên một account thử (đo, không đoán). *(Phase 4 đã có `flood_log` và `limiter_state` để đo; chưa có số liệu thật, các mặc định vẫn là điểm khởi đầu bảo thủ. Phase 19d1 (kế hoạch 2026-10-15) thêm ngữ cảnh vào `flood_log` để câu hỏi này trả lời được theo từng hành động/đích; số liệu thật từ 2026-10-16 ghi ở spike 15.)* 7. Với `drop_author=True`, Telegram xử lý thế nào các loại poll, quiz, location, contact, game, invoice khi forward (giữ, lỗi, hay đổi thành tin khác)? Quyết định chiến lược A có cần tiền kiểm theo loại tin hay không. 8. Quiz: admin/creator của nguồn có thấy đáp án đúng khi chưa trả lời không? (Telethon chỉ dựng lại được quiz khi có `results.results`.) Kiểm tra `poll.id`, `close_date`, `public_voters` có được chấp nhận khi gửi lại `InputMediaPoll`. 9. **Đã cài ở phase 8 (2026-09-25), chưa kiểm chứng trên Telegram thật.** Forum: `ForwardMessagesRequest(top_msg_id=...)` có đưa tin vào đúng topic đích không; `CreateForumTopicRequest` (icon, General); `iter_messages` trả `reply_to.forum_topic`/`reply_to_top_id` đủ để định tuyến topic (và có đúng là tin ở General **không** có `reply_to` như đã giả định không); `ToggleForumRequest` để tạo đích forum; danh sách topic (`GetForumTopicsRequest`) và topic đã đóng/ẩn; một tin không có `top_msg_id` có được Telegram tự định tuyến vào General không. Xem "Phase 8 — ghi chú". 10. ~~`messages.search` (`limit=1`, `min_id`/`max_id`, filter, `q`) có áp khoảng và phần lọc khi tính `count` không?~~ **Xong một phần 2026-09-20** (`scripts/spike_count.py`, kênh 72 tin, id mới nhất 114): **filter media được áp** (17 video = 17 khi đọc), **`min_id`/`max_id` bị bỏ qua** (luôn trả tổng 72; đọc thật sau id 57 là 34, tới id 57 là 38). Bản đầu của `count` vì vậy sai với mọi khoảng; đã sửa thành đếm theo *vị trí* (`offset_id_offset`, xem `01-kien-truc.md`): cần chạy lại spike để xác nhận mọi dòng "same". Chưa thử: `search` có từ khớp (kênh thử không có `#news`), filter ảnh có ảnh. 11. **Xong một phần 2026-09-20 (kênh không cấm lưu nội dung)**: gửi lại media **bằng tham chiếu file** — `send_file(dst, message.media, caption=...)` — được chấp nhận: video 56 MB (thời lượng 1232 s) và tệp `.srt` ra đúng loại, đúng dung lượng, không tải xuống hay tải lên. Thêm: video 184 MB (1504 s) cũng được. **Album cũng được** (2026-09-20, `send_file(dst, [media, ...])`): 6 video 115–490 MB ra 6 tin video đúng thời lượng, **cùng một nhóm album** ở đích. **Nguồn `noforwards` (D3), 2026-09-21: bị từ chối** — album 2 video (321 MB và 175 MB) với `--yes-i-administer-this-channel`: `ChatForwardsRestrictedError: You can't forward messages from a protected chat` do `SendMultiMediaRequest`; tin đơn chưa thử riêng (chạy không có `--album`). Chưa biết: `FILE_REFERENCE_EXPIRED` sau bao lâu, caption/entity/ảnh bìa có đúng không, thời gian gửi. Câu hỏi gốc: (`send_file(dst, message.media, caption=...)`, không tải, không tải lên) có được Telegram chấp nhận không, loại media (video, thời lượng, voice, sticker) có giữ nguyên không, album bằng danh sách media có giữ nhóm không, `FILE_REFERENCE_EXPIRED` xảy ra sau bao lâu? (`scripts/spike_reference.py`; ca nguồn `noforwards` theo D3.) 12. **Xong một phần 2026-09-20** (`scripts/spike_throughput.py`, tài khoản của người dùng, DC 5 là DC nhà, mỗi setting 3 lần lấy trung vị; đường truyền của máy thử khoảng 30–40 MB/s). **Tải xuống** (video 55 MB): Telethon `iter_download` 4,2 MB/s; request thô 1 MiB, 1 đang bay 6,9; 2 đang bay 15,6; 4 đang bay 28,6; 8 đang bay 34,3 (29–40), tất cả trên **một** kết nối. Thêm kết nối không giúp gì (2 request/2 kết nối 14,9 = 2 request/1 kết nối), và cấu hình 4 request/2 kết nối bị server đóng kết nối (`Server closed the connection`) khiến script treo (đã sửa: mỗi setting có timeout và báo lỗi). **Tải lên** (64 MB, big file, nhiễu lớn: có lần 4 request/1 kết nối chỉ 2,5 với một lượt 14,2): 1 request 3,5; 2 request 8,6; 8 request/1 kết nối 18,9 (5,3–19,1); 2 kết nối 2/4/8 request 9,5/14,7/15,5; **4 kết nối × 8 request 26,8 (22–29)**, cấu hình ổn định nhất. Không FloodWait ở cả hai chiều. Kết luận sơ bộ: **tải xuống chỉ cần một kết nối với 4–8 request đang bay** (nhanh gấp 5–8 lần cách hiện tại, khỏi cần `exportAuthorization` hay sender thứ hai cho DC nhà; DC khác dùng sender mượn của Telethon vẫn là một kết nối); **tải lên cần nhiều kết nối** (2–4) với khoảng 8 request đang bay, và việc tạo kết nối phải chịu lỗi được (lùi về ít kết nối hơn khi server đóng). Cách hiện tại (một request một lúc) là 4 MB/s xuống và 3,5 MB/s lên: video 55 MB mất khoảng 13 s + 16 s. **Tải xuống và tải lên cùng lúc** (`both`, tải 8 request/1 kết nối, lên 8 request/2 kết nối, 54 MB mỗi chiều, 3 lần): riêng lẻ tải xuống 29,7 và tải lên 21,2 (14,6–24,6); cùng lúc tải xuống vẫn 29,0 nhưng tải lên 16,2 (một lần **0**), và trong một lần có lỗi tầng truyền: `Invalid response buffer (HTTP code -100)`, `invalid checksum`, rồi **`HTTP code 429` ở tầng truyền — Telegram báo flood ngay trên kết nối, không phải `FloodWaitError`**; các lần sau vẫn chạy được. Đây là bằng chứng rằng **16 request đang bay trên 3 kết nối là quá tay**. Hệ quả cho thiết kế: trần tổng số request đang bay nên nhỏ (khoảng 8 chia cho cả hai chiều, khởi đầu 4 + 4) và tổng số kết nối ≤ 3 (1 xuống + 2 lên); `InvalidBufferError` mã 429 phải được ánh xạ thành tín hiệu flood (lùi một nửa, ghi `flood_log` với loại riêng như `transport_429`, chờ rồi tăng lại), các `InvalidBufferError`/`Server closed the connection` khác là lỗi kết nối để kết nối lại và lùi; gửi cùng một part lại sau lỗi. Câu hỏi gốc: một kết nối một request so với K request đang bay trên một kết nối, so với K kết nối; FloodWait có xuất hiện khi K lớn không; giới hạn tải xuống của tài khoản không Premium? (`scripts/spike_throughput.py`.) Quyết định cần bao nhiêu kết nối và `R` mặc định. 13. Giới hạn dung lượng upload của tài khoản (2 GB hay 4 GB Premium; theo tôi nhớ có trong cấu hình phía server `upload_max_fileparts_*`): analyze cần báo file vượt giới hạn trước khi chạy, không đợi tới lúc lỗi. 14. **Phase 18a, xong một phần 2026-10-12** (xem "Phase 18a — ghi chú"): đã xác nhận trên tài khoản thật `reply_to` trong forum, `fwd_from`, `file_key` qua forward, tổng `reactions` và thời gian quét 13.000 tin (2 phút 22 giây). **Để sau (người dùng chốt 2026-10-12, không chặn gì)**: `InputMessagesFilterUrl` có thu hẹp an toàn cho predicate `link` không — người dùng thử `--has-link` có và không `--no-pushdown` (2026-10-12) và cho cùng kết quả, đúng như dự đoán — nhưng vì `link` chưa được đẩy xuống nên hai lần chạy giống nhau là hiển nhiên, **chưa trả lời** được filter của server có bỏ sót không (cần cài pushdown thử rồi so lại); quét kênh ~100.000 tin thật. 15. **Rate limit thật của phía ghi (Phase 19d).** Không có script riêng: dữ liệu là `flood_log` của các lần dùng bình thường (19d1 ghi đủ làn, đích, `sent_1h`/`sent_24h`, Premium). Câu hỏi: ngưỡng `short_flood` nào tách đúng "tốc độ tức thời" và "hạn mức cửa sổ"; `X` ≤ 1 giờ có ứng với cửa sổ 1 giờ không; giới hạn tính theo đích hay theo account; tính theo **lời gọi** hay theo **tin**; ngân sách 80%/×0,5/+10% có giữ lần chạy sau khỏi bị chặn không. Các điểm dữ liệu: - **2026-10-14 → 16, lần chạy 41–68** (người dùng, tài khoản **Premium**, `delay` 2 s suốt). Nguồn số liệu: `runs` + `msg_map` (thời điểm từng tin đã gửi, `batch_id`, `grouped_id`) cho số tin, và `flood_log` cho lần flood. Người dùng đã xoá `flood_log` vài lần, nên chỉ còn các lần flood từ 2026-10-16 12:37 UTC; `runs`/`msg_map` thì còn đủ. "Unit" = một album hoặc một tin lẻ ≈ một lời gọi ghi khi gửi lại; một lời gọi forward chở cả batch. Cửa sổ 60 phút đậm nhất của từng đích: | Đích (loại) | Lần chạy | Tin / unit / batch trong 60 phút đậm nhất | Kết cục | |---|---|---|---| | Livestream chat (forum cũ, định tuyến topic) | 51, 2026-10-14 18:02 | 2917 / 1367 / 1099 | Không có flood dài làm dừng; lần chạy 51 dừng vì **cap cũ 5000** (`daily_cap`, 5478 tin) | | LivestreamRaw (broadcast) | 55, 2026-10-16 13:51 | 2970 / 2072 / 89 | Không bị chặn | | StripRaw (broadcast, vừa tạo) | 61–65, 2026-10-16 15:04 | 3358 / 3277 / 64 | Không bị chặn | | SwagLiveRaw (broadcast, vừa tạo) | 67, 2026-10-16 16:03 | 3366 / 3123 / 170 | Không bị chặn | | **OnlyFans (forum vừa tạo đầu lần chạy, định tuyến topic)** | **68, 2026-10-16 16:34** | **1907 / 575 / 575 trong 31 phút** | **`FLOOD_WAIT` 1737 s** trên `send_by_reference` | - **Lần flood dài**: đến **31 phút** sau khi lần chạy 68 bắt đầu (16:34:18 → 17:05:21 UTC), sau 575 lời gọi gửi bằng mã file chở 1907 tin, trong đó 1666 tin nằm trong album (`SendMultiMedia`). Tức là khoảng 18,5 lời gọi/phút, 61 tin/phút. Không có flood ngắn nào báo trước. `flood_log` ghi `sent_1h` 1882 (xô giờ là xấp xỉ, `msg_map` đếm 1907), `sent_24h` của làn 2026. Account đã gửi **14.327 tin trong 24 giờ** trước đó (cảnh báo `daily_cap` bật). Limiter học ngân sách **1506 tin/1 giờ** cho làn `send` của đích này (đúng thiết kế 19d2: 80%, cửa sổ 1 giờ vì `X` ≤ 3600 s). - **Đọc**: 8 flood ngắn 3–6 s trên `iter_messages` (làn `history`), đều dưới `short_flood`. Chỉ tăng delay đọc, đúng như mong đợi. - **Đọc thế nào (chưa phải kết luận)**: 1. **Theo số lời gọi, OnlyFans không nhanh hơn Livestream chat** (khoảng 1100 so với 1367 unit/giờ quy đổi), nhưng **theo số tin thì nhanh hơn** (khoảng 3700 so với 2917 tin/giờ quy đổi), vì phần lớn là album. Đó là gợi ý, chưa phải bằng chứng, rằng phía gửi lại bị đếm theo **tin/media**, không chỉ theo lời gọi. Cách ngân sách 19d2 đang đếm (theo tin) khớp với gợi ý đó. 2. **Forward chở nhiều tin hơn hẳn mà không bị chặn** (khoảng 3.300 tin/giờ trong chỉ 64–170 lời gọi). Không tách được "forward được nới hơn gửi lại" với "forward ít lời gọi hơn". 3. **Đích vừa tạo** không đủ để giải thích một mình: StripRaw và SwagLiveRaw cũng vừa tạo mà không bị chặn, nhưng đó là broadcast + forward. Forum vừa tạo + gửi lại album thì chỉ có một điểm. 4. **`X` = 1737 s đến sau 31 phút**: nếu là hạn mức theo cửa sổ thì cửa sổ có thể ngắn hơn 1 giờ, hoặc đó là ngưỡng tốc độ (tin/phút) chứ không phải tổng theo giờ. Một điểm chưa phân biệt được. 5. Chưa nói được gì về "theo đích hay theo account". - **2026-10-17, lần chạy 69** (`tgmirror run 68` sau `resume_at`, cùng đích OnlyFans, ngân sách đã học 1506 tin/1 giờ): - Gửi **1478 tin trong 17 phút** (02:15:08 → 02:32:08 UTC) bằng **254 lời gọi**, 1416 tin trong album: khoảng 87 tin/phút và 15 lời gọi/phút. Tức là **nhanh hơn lần chạy 68 tính theo tin** (61 tin/phút), **chậm hơn tính theo lời gọi** (18,5/phút), và album to hơn (5,8 so với 3,3 tin mỗi lời gọi). - **Telegram không chặn.** Chính ngân sách của tgmirror dừng lần chạy (xô giờ 02:00 UTC đạt 1506), ở `waiting_flood`/`daily_cap`, `resume_at` 04:00 UTC (11:00 giờ máy). - **Đọc thế nào**: không mâu thuẫn với hạn mức theo cửa sổ (dừng ở 1506, dưới mức 1907 lần trước bị chặn). Nhưng cũng không kiểm được 80% có quá chặt không (ngân sách chặn trước khi Telegram kịp lên tiếng), và vẫn không tách được "đếm theo tin" với "đếm theo lời gọi" (cả hai lần đều dưới ngưỡng ở một trong hai cách đếm). Tốc độ 87 tin/phút mà không bị chặn cho thấy giới hạn ở lần 68 **không phải một ngưỡng tốc độ tin/phút đơn thuần**. - **Hai chỗ chưa ổn của 19d2 lộ ra** (**đã sửa 2026-10-17**, xem "19d2 — sửa sau lần chạy thật" dưới): 1. **`run.cap_days`/`status.line_cap` làm tròn lên thành ngày**: với ngân sách 1 giờ, còn 3082 tin chỉ cần thêm khoảng 2 cửa sổ (2 giờ), nhưng câu báo là "cần nghỉ thêm khoảng 1 ngày" (`engine/status.py::cap_days` quy giờ ra ngày, làm tròn lên). Với cửa sổ dưới 24 giờ cần nói theo giờ. 2. **Xô giờ quá thô cho cửa sổ 1 giờ**: một xô chỉ được nhả khi cả giờ của nó đã ra khỏi cửa sổ (`Limiter._resume_at`, cố ý để không bao giờ sớm), nên lần chạy bắt đầu 02:15 phải đợi tới 04:00, tức 1 giờ 45 phút chứ không phải 1 giờ. Tốc độ thực tế tụt còn khoảng 1506 tin mỗi 1 giờ 45 phút. Muốn sát hơn thì cần xô nhỏ hơn (ví dụ 5 phút) cho cửa sổ 1 giờ; đổi lại là một migration của `sent_hours`. - **2026-10-17, lần chạy 70** (`tgmirror run 68` lần nữa, chạy sau bản sửa ô 5 phút; bắt đầu 04:48 UTC, 48 phút sau `resume_at` của lần 69): - Gửi **1478 tin trong 17,7 phút** (04:48:38 → 05:06:19 UTC), 295 lời gọi, 1411 tin trong album: 83 tin/phút, 17 lời gọi/phút, cùng cỡ lần 69. **Telegram lại không chặn**; ngân sách của tgmirror dừng lần chạy ở 1506 tin trong cửa sổ (các ô 04:45–05:05: 152 + 413 + 448 + 410 + 83). - **Bản sửa chạy đúng**: `resume_at` = 05:50 UTC (12:50 giờ máy) = ô 04:45 + 1 giờ + 5 phút, tức đợi 44 phút. Với ô 1 giờ thì phải đợi tới 06:00 UTC (sau 54 phút) và tới 07:00 nếu ô 04:00 còn tin; dòng "cần nghỉ thêm khoảng 1 giờ" cho 1600 tin trên 1506/giờ cũng đúng (trước là "1 ngày"). - **Lần chạy này không kiểm được ngân sách 1506**: hai lần liền (69, 70) tgmirror tự dừng ở 1506 trước khi Telegram lên tiếng, nên vẫn chưa biết 1506/giờ là dưới hạn mức thật bao nhiêu. Tốc độ được phép 83 tin/phút duy trì 18 phút vẫn sạch, khớp với "hạn mức tính theo cửa sổ và theo tin", không khớp với "ngưỡng tin/phút" (lần 68 bị chặn ở 61 tin/phút sau 31 phút). Chỉ ngân sách tăng dần (+10% mỗi 24 giờ từ 2026-10-16 17:05, tức tới 1657 tin/giờ vào 17:05 UTC 2026-10-17) hoặc một lần chạy dài hơn mới đẩy được tới hạn mức thật. - `flood_log` không có dòng mới nào từ 2026-10-17 (không flood, kể cả flood đọc). - **Cần xem tiếp** (cho cả hai điểm trên): các lần `run` tiếp theo trên OnlyFans có bị Telegram chặn trước khi chạm 1506 không (nếu có thì 80% là chưa đủ, hoặc cửa sổ dài hơn 1 giờ). Lần chạy 69 chưa trả lời được vì dừng ở chính ngân sách; một lần gửi lại album vào một forum **cũ** với cùng tốc độ, để tách yếu tố "đích mới"; một lần gửi lại tin lẻ (không album) tới cùng số tin/giờ, để tách "đếm theo tin" với "đếm theo lời gọi". ## Câu hỏi mở Hiện không có. Năm câu của đề xuất 2026-10-18 (định tuyến tổng quát, gộp/chia topic, sửa tin) đã trả lời cùng ngày: `07-inspect-transform.md`, mục 11.6. Các câu hỏi phát sinh trong lúc thiết kế đều đã được trả lời (bảng dưới; ba câu của Phase 19d trả lời 2026-10-15, ở "Phase 19d — kế hoạch"). ## Câu hỏi đã trả lời (2026-09-19) | Câu hỏi | Trả lời | Nơi ghi | |---|---|---| | Nguồn là supergroup/group hay chỉ broadcast? | Tất cả: broadcast, supergroup, group, forum | `00-tong-quan.md` (mục tiêu), `01-kien-truc.md` | | Forum: ánh xạ topic → topic ở đích? | Có | `01-kien-truc.md`, `04-state-checkpoint.md` (`topic_map`) | | Chế độ chạy nền (daemon)? | Không, không lên lịch. Chỉ chạy tay: `clone`/`run` chạy ngay trong terminal (lúc đó gọi là `sync`, nay là chạy lại) | `00-tong-quan.md` (không phải mục tiêu) | | Nhiều account? | Không, một account | `00-tong-quan.md` (không phải mục tiêu) | | Tên PyPI/GitHub còn trống? | Không (`twingram` đã bị chiếm). Chọn **tgmirror** | `00-tong-quan.md` (Tên dự án) | | Poll/quiz/location/contact/invoice/game khi copy? | Location/contact: giữ. Poll: giữ nhưng mất vote (opt-in `--reset-polls`). Quiz: giữ nếu đã trả lời. Game/invoice: bỏ + cảnh báo (`--ignore-unsupported`) | `01-kien-truc.md`, `02-cli-ux.md`, `04-state-checkpoint.md` | | Đích có sẵn của nguồn group/forum bắt buộc cùng loại (forum → forum)? | Đổi ở phase 8 (2026-09-25): **không**, mọi cặp loại được phép; chỉ forum → không-phải-forum cảnh báo mất topic. Xem "Phase 8 — ghi chú" | `01-kien-truc.md` | | Thêm tiền tố tên người gửi khi copy từ group (chiến lược B)? | Không cần | `01-kien-truc.md` (Hạn chế khi copy từ group) | | Cờ gửi tin text thay thế cho tin bị bỏ? | Có: `--placeholder` | `01-kien-truc.md`, `02-cli-ux.md` | ## Nhật ký quyết định Khi đổi một quyết định D1..D9 trong `00-tong-quan.md`, ghi ngày và lý do ở đây. - 2026-10-24: **Phát hành `v0.3.0`** theo yêu cầu người dùng ("release luôn"), từ commit `249d1ef` (CI xanh trên Windows và Ubuntu, Python 3.11 và 3.14). `release.yml` chạy xong: build + test, zip PyInstaller Windows, ảnh Docker `0.3.0` rồi `:latest`, PyPI (Trusted Publishing) và GitHub Release (wheel, sdist, zip Windows, `SHA256SUMS`) — kiểm lại trực tiếp: PyPI trả `0.3.0`, Docker Hub có `0.3.0` và `latest`. Job `winget-release` **fail như dự kiến** (`tamvcspk.tgmirror does not exist in microsoft/winget-pkgs`: PR #442694 chưa merge, xem Phase 14). 0.3.0 gồm Phase 21, 20 (20.1–20.5), 20b và 17. Chưa thử thật (không chặn, README nói rõ): các mục menu mới (cần terminal), màn hình Khám phá, `inspect --quick`, kill cứng khi gộp hàng nghìn tin. - 2026-10-24: **Phần còn thiếu của 17/20b/20.x xong** theo yêu cầu người dùng ("làm tiếp phần còn thiếu"): mục menu full-screen "Sửa chữ của tin…", "Đăng lại tin…", "Topic của một forum…", "Đồng bộ thay đổi của nguồn…" (`ui/menu/screens/{edit,repost,topics,sync}.py`; `OpScreen` chạy được `repost`/`move` — D3, tải xuống — và nhiều thao tác nối tiếp); `sync-changes --src/--dst/--min-id/--max-id`; `topics split` nhận cờ lọc và `--selection`. Đã thử thật `sync-changes` với nguồn là forum, `--src/--dst` và `--min-id`; các mục menu mới kiểm bằng test (cần terminal thật để bấm thử). Không đổi D1–D10. - 2026-10-24: **Phase 20b xong (chia/gộp/xoá/đổi tên/đóng topic tại chỗ)** theo yêu cầu người dùng ("làm hết luôn lát này và test một lượt"): `tgmirror topics split|merge|delete|rename|close|reopen|move`, `OpKind.MOVE`, `engine/topicops.py`, gateway `edit_topic`/`delete_topic`/`topic_message_ids`. Không đổi D1–D10, không migration. Đã thử trên Telegram thật cùng ngày (forum «Mediacenter» của người dùng, topic thử tự tạo, đã dọn). Với 20b, mọi mục của 0.3.0 đã có code. Xem "Phase 20b — ghi chú". - 2026-10-24: **Phase 17 xong (đồng bộ edit/delete nguồn → bản sao)** theo yêu cầu người dùng ("hoàn tất luôn phase 17, implement, unit test và test trên kênh thật, dùng lại kênh đang được sử dụng để test"): `tgmirror sync-changes`, `engine/sync.py`, `Store.mirror_copy_rows`, `OpRunner._back_at_source`. Không đổi D1–D10, không migration; chỗ khác đề xuất `07` mục 6.5 (không dùng chỉ mục metadata vì nó không bao giờ là cơ sở của một lần ghi; đọc lại nguồn khi áp dụng) ghi ở "Phase 17 — ghi chú". Đã thử trên Telegram thật cùng ngày với kênh `mediacenter` riêng tư và kênh test cũ của người dùng (tin thử có hashtag duy nhất, đã dọn về đúng số tin ban đầu). - 2026-10-23: **Người dùng cho thử thật** trên các kênh `mediacenter` của họ (cho tin thử; kênh test mới do tgmirror tạo cho phần ghi). Phase 20.1 `delete` đạt (chi tiết ở "Phase 20 — ghi chú"); thiếu sót limiter không lưu trạng thái sau lô đã sửa. Phase 21 thử thật: `inspect --by route`, `--plan ... --dst-no-topics`, `--hashtag-to-topic` với `--topic-skip/--topic-pick/--topic-limit` vào forum mới (topic đúng, `#st` bị bỏ qua, lấy hashtag cuối), cùng nguồn vào kênh không phải forum (nhãn thành hashtag, gửi lại). Cũng chạy qua: `clone` (copy/reupload `strip-links`/`--selection --exact`/`--fresh`/delta), `backup` + `restore`, `pause`/`stop` từ terminal khác, `retry` (không có tin lỗi), `inspect` (quét, `--csv`, `--save --freeze`, `--list`, `--quick`, `--plan`), `appdata export`, `doctor`, `limits`, `status`, `history`. Chưa thử thật: bước wizard "Chia tin theo hashtag?" (cần terminal thật) và phím `t` của màn Khám phá. Một lần `restore --dst-new` báo "Telegram returned an unexpected result for the new channel" (kênh vẫn được tạo; lần chạy lại và một lần tạo trực tiếp thì bình thường) — chưa tái hiện được, ghi lại để theo dõi. Không đổi D1–D10. - 2026-10-18: **Phase 20 bắt đầu: lát 20.1 `delete` xong code** theo yêu cầu người dùng ("tiếp tục việc kế tiếp" sau Phase 21): `ops`/`op_items` (migration 8), làn `delete`, `plan_delete`/`OpRunner`, `tgmirror delete`, `O` trong `history`/`pause`/`stop`. Theo D10 (đã duyệt 2026-10-12) và lệ "khi Phase 20 bắt đầu" của `07` mục 7: thêm luật cứng 11 vào `CLAUDE.md`, sửa "Mục tiêu" của `00-tong-quan.md`. Không đổi D1–D10. Chia Phase 20 thành năm lát (20.1–20.5), xem "Phase 20 — ghi chú". - 2026-10-18: **Người dùng duyệt hướng mục 11 của `07-inspect-transform.md`** (trả lời 5 câu ở 11.6): (1) một tin một topic, không nhân bản; (2) ca tên file trong caption giải theo `from: text` + `regex` + `to` như đề xuất ("không có đường" = không có cách); (3) `route` dùng cho cả topic (đích forum) lẫn hashtag (đích khác, theo `hashtag_format`); (4) Phase 21 vào **0.3.0**; (5) làm Phase 20b: chia → đăng lại các tin chuyển vào topic mới đúng thứ tự gốc rồi xoá chúng khỏi topic cũ; gộp → đăng lại tin của topic sau vào cuối topic trước theo thứ tự rồi xoá topic sau. Chưa viết mã, không đổi D1–D10. - 2026-10-18: Theo yêu cầu người dùng, **bổ sung vào plan** gộp/chia topic và sửa tin cho forum, và brainstorm cho hai ca gặp khi dùng 19b (tin nhiều hashtag chỉ lấy hashtag đầu; tên file trong caption, không có hashtag, muốn trích bằng regex làm tên topic). Đề xuất một cơ chế chung thay cho xử lý từng ca: **luật định tuyến `topics.route`** (điều kiện = ngôn ngữ filter, trích khoá bằng regex từ hashtag/caption/tên file/topic nguồn, `pick`, mẫu tên với bộ lọc cố định; `hashtag_to_topic` thành cú pháp tắt) — Phase 21 mới; gộp/chia tại chỗ là Phase 20b trên `repost`/`delete` của Phase 20; `edit` thêm sửa theo `msg_map`. Toàn bộ ở `07-inspect-transform.md` mục 11, **chưa duyệt**, 5 câu hỏi ở mục 11.6. Không viết mã, không đổi D1–D10. - 2026-10-15: **Phase 19d2 xong code** (ngân sách tự học theo làn ghi, cửa sổ trượt, `daily_cap` chỉ cảnh báo, `BudgetReached` thay `DailyCapReached`, migration 5, `[limits] short_flood`); cùng `19d1`, thuộc 0.2.0. Chi tiết và chỗ khác bản kế hoạch ở "19d2 — đã cài". Tag `v0.2.0` còn chờ người dùng thử trên Telegram thật. - 2026-10-17: **Thêm Phase 19d4 (thăm dò giới hạn)** vào kế hoạch theo điểm mù người dùng chỉ ra (ngân sách học được chỉ giảm khi bị chặn và gần như không bao giờ được thử vượt; lần chạy 69, 70 tự dừng ở 1506 mà chưa biết hạn mức thật). Người dùng chốt ba điểm: reset/thăm dò là hành động chủ động bằng cờ (không hỏi lại), không có cờ thì hỏi khi đang trong giới hạn; các cờ này không đổi cặp/filter (một tùy chọn không đổi bộ lọc không tạo job mới, đúng với code hiện tại); câu hỏi theo tuổi của lần kiểm chứng giới hạn. Chưa code. Không đổi D1–D10. - 2026-10-17: Người dùng đồng ý tách release 19d4 (`limits`/`limits reset`/`--reset-limits` kèm 0.2.0, `--probe` và câu hỏi tự động sau) và đồng ý không hỏi khi giới hạn vừa được kiểm chứng; chốt giữ tăng +10%/24 giờ nhưng chặn ở 95% của `bad`, đứng yên khi chạm trần hoặc khi `bad` hết hạn cho tới khi thăm dò hoặc bị chặn. Phát hiện `grow_budget` hiện không có trần (vượt `bad` từ 2026-10-19), nên phần trần vào 0.2.0. - 2026-10-17: **Phát hành `v0.2.0`** theo yêu cầu người dùng ("release 0.2.0"), từ commit `2f7a682` (CI xanh trên Windows và Ubuntu). `release.yml` chạy xong: build + test, zip PyInstaller Windows, ảnh Docker `0.2.0` rồi `:latest`, PyPI (Trusted Publishing) và GitHub Release (wheel, zip Windows, `SHA256SUMS`) đều xong. Job `winget-release` **fail như dự kiến** (`tamvcspk.tgmirror does not exist in microsoft/winget-pkgs`: PR #442694 chưa merge, xem Phase 14). `--probe` và câu hỏi tự động sang release sau. Tag `v0.2.0rc1` (14/10) đã fail ở bước kiểm tag = version và không phát hành gì. - 2026-10-17: Người dùng chạy `inspect --refresh` trên một kênh thật 60.395 tin (1,9 TB): chạy hết, chỉ mục 41 MB (~714 byte/tin). Ghi ở "Phase 18b — ghi chú", "Đo trên kênh lớn". `--probe` để sang release sau (người dùng xác nhận, như kế hoạch). - 2026-10-17: **Phase 19d4 cài phần kèm 0.2.0** theo yêu cầu người dùng ("Hãy implement", phần `ok`/`bad`/trần 95%/`limits`/`limits reset`/`--reset-limits` đã chốt ở (a)): migration 7, `[limits] probe_after_hours`. `--probe`, thăm dò và câu hỏi tự động vẫn để sau 0.2.0. Xem "19d4 — đã cài". - 2026-10-17: **Sửa hai lỗi của 19d2** lộ ra ở lần chạy thật 69 (spike 15), theo yêu cầu người dùng ("sửa cả hai"): thời gian nghỉ báo bằng giờ thay vì làm tròn lên ngày, và bộ đếm của cửa sổ trượt đổi từ ô 1 giờ sang ô 5 phút (migration 6, `sent_hours` → `sent_buckets`). Không đổi D1–D10, không đổi ngưỡng/hệ số học (80%/×0,5/+10%/`short_flood` giữ nguyên). Xem "19d2 — sửa sau lần chạy thật". - 2026-10-15: Người dùng trả lời ba câu hỏi của Phase 19d: `daily_cap` chỉ còn là trần an toàn **cảnh báo, không chặn**; **cửa sổ trượt 24 giờ** thay cho mốc 00:00; **19d1 + 19d2 thuộc release 0.2.0** ("5000 tin và 00:00 làm trải nghiệm như không xài được"). Hệ quả ghi vào kế hoạch: 19d2 không đợi dữ liệu thật của 19d1 (ngưỡng `short_flood` tạm 60 s, chỉnh ở bản vá); một làn chưa gặp flood dài thì không có ngân sách; tag `v0.2.0` đợi 19d2. Không đổi D1–D10. - 2026-10-15: **Thêm Phase 19d — rate limit thích nghi** vào lộ trình, theo yêu cầu người dùng ("rate limit thông minh hơn thay vì cứng 5000 tin/ngày, gắn với các yếu tố ảnh hưởng"). Đề xuất ba phương án (A profile tĩnh, B ngân sách tự học theo khóa, C chỉ phản ứng); người dùng yêu cầu ghi kế hoạch theo B trước, chưa code. Không đổi D1–D10 (D6 giữ nguyên). Thiết kế ở `05-chong-flood.md`, lát cắt và ba câu hỏi còn mở ở "Phase 19d — kế hoạch". Cùng lúc ghi lại kết quả đối chiếu một bản tổng hợp "rate limit chính thức" mà người dùng đưa (part tải lên 512 KB chứ không phải 1 MB; "3–5 kết nối" và "phạt lũy tiến" không có trong docs chính thức; Takeout chỉ giúp phía đọc). - 2026-10-12: **Phase 18a bắt đầu và xong code** theo yêu cầu người dùng ("bắt đầu phase 18"): `tgmirror inspect`, metadata/predicate mới, pre-flight, file selection, `--selection`/`--exact`, wizard "dùng kết quả khám phá". Không đổi D1–D10; những chỗ khác với đề xuất `07` (hai cờ cho link, `link` không đẩy xuống server, `--exact` bằng predicate `message_ids`, `@last` luôn kèm id, ...) ghi ở "Phase 18a — ghi chú". Chi tiết thiết kế đã chuyển sang `01`–`03` như `07` dặn. Người dùng thử trên Telegram thật cùng ngày (reply/forward/duplicate/reactions/thời gian quét): đạt; xem spike 14. - 2026-10-12: Người dùng xác nhận **Đợt 4 của Phase 15b xong** (phần thử thật: restore backup thật, dừng/tiếp trong menu, kill giữa backup, hai terminal → `SessionBusy`, dời thư mục backup) → Phase 15b xong; Phase 16 đã ghi xong từ trước (2026-09-28). Theo yêu cầu người dùng, **rút gọn "Trạng thái hiện tại" và bảng "Lộ trình"** thành một dòng mỗi phase (chi tiết vẫn nằm nguyên ở các mục "Phase N — ghi chú"), chia theo release (0.1.x đã phát hành, 0.2.0, 0.3.0) và thêm Phase 18a/19/18b/20 cùng thứ tự làm. Nhân tiện tick ô N2+N3 của Đợt 1 (đã làm 2026-09-27, kiểm lại trong code, chỉ quên tick). Không đổi D1–D10. - 2026-10-12: **Người dùng duyệt kế hoạch `07-inspect-transform.md`** (cả 7 câu hỏi): (1) **thêm D10** — cho ghi/xoá tại chỗ trên kênh của user, chỉ khi có xác nhận (bảng quyết định ở `00-tong-quan.md`; `CLAUDE.md` và skill `doc-sync` đổi "D1–D9" thành "D1–D10"); (2) tách hai release 0.2.0 (Phase 18a, 19, 18b) và 0.3.0 (Phase 20); (3) dùng lại filter bằng file selection + `@last` + in lệnh kế tiếp; (4) chỉ mục metadata là file riêng theo nguồn trong cache dir; (5) backup trước khi xoá là tùy chọn, hỏi Có/Không; (6) inspect không cần D3 kể cả khi xuất caption/text — D3 chỉ khi tải media hay đăng lại; (7) Phase 17 dời ra sau Phase 20. Chưa viết mã. - 2026-10-12: Brainstorm và lên kế hoạch cho release sau 0.1.1 theo yêu cầu người dùng: inspect/report bằng filter và dùng lại selection cho clone/backup/restore, transform khi sao chép (topic ↔ hashtag, ...), thao tác hàng loạt tại chỗ (xoá, sửa, đăng lại). Không viết mã, không đổi D1–D9. Toàn bộ đề xuất (mô hình Selection × Transform × Target, UX dùng lại filter, plan/apply, Phase 18–20, hai release 0.2.0/0.3.0, spike) ở `07-inspect-transform.md`, **chưa duyệt**; 7 câu hỏi chờ người dùng ở mục 10 của file đó, trong đó một quyết định mới (đề xuất D10: cho ghi/xoá tại chỗ trên kênh của user) phải chốt trước Phase 20. - 2026-09-28: **Đóng khoảng trống "chưa phân tích/ETA" của Phase 11a** (ghi ở "Phase 11a — ghi chú", "Phase 15a — ghi chú"): người dùng nhận thấy màn hình "Backup" trong menu full-screen không có thanh tiến độ, và màn hình "Kênh đã join" không dùng được ↑/↓ (lỗi thứ hai, không liên quan, sửa riêng cùng phiên — thêm `ui/menu/widgets.py::SelectList`/`Fit` cho `ChannelsScreen`), rồi hỏi cả bốn màn hình chạy việc (clone/run/backup/restore) nên dùng chung một giao diện tiến độ. Không đổi D1–D9. Đọc code cho thấy clone/run/retry/restore đã dùng chung `RunScreen`/`TuiReporter` từ trước; chỉ `backup` khác, vì `Backup` chưa từng có tổng số tin để tính %/ETA (đúng như Phase 11a đã ghi là cắt phạm vi có chủ đích). Đã thêm: `BackupWriter._analyze` (mirrors `Runner._analyze`) gọi `reader.count(...)` — cơ chế đã tổng quát cho cả run lẫn backup từ `engine/flood.py::FloodOwner`, chỉ chưa ai gọi tới cho backup — lưu qua `Store.set_backup_total` (đè `stats_json["total_items"]`, không cộng dồn như `advance_backup`); `engine/status.py::backup_estimate` (rút phần công thức chung với `estimate` ra một hàm nội bộ `_estimate`); `ui/progress.py` có thêm `bar`/`progress_line`/`floods_tail`/`TransferLines` dùng chung giữa `TuiReporter` và `BackupTuiReporter` (rồi cả `LineReporter`/`BackupLineReporter`, trước đây `BackupLineReporter.transfer` là no-op). Không dựng một lớp/kiểu chung cho cả hai reporter (`TuiReporter` có dst/mode/failed mà `BackupTuiReporter` không có) — chỉ rút phần thực sự giống nhau, tránh đúng kiểu "ép một trừu tượng lên hai hình dạng khác nhau" CLAUDE.md đã cảnh báo. Việc phát sinh không lường trước: `_analyze` của backup không có "đã phân tích rồi thì bỏ qua" như run's `retry_of`, vì mỗi backup là một dòng `INSERT` mới (không như run có thể tiếp tục trong cùng một lời gọi `run()`) — không cần bảo vệ trùng lặp, gọi lại mỗi lần `run()` là an toàn (kiểm bằng agent Plan trước khi sửa code). Test mới: `tests/integration/test_backup.py::test_analyzes_a_total_like_a_run_does`, `tests/unit/test_status.py` (bốn test `backup_estimate`), `tests/unit/test_transfer.py::test_a_backup_download_gets_the_same_big_file_lines_a_run_does`, `tests/unit/test_backup_tui.py` (mới, bảy test, mirrors `test_tui.py`). - 2026-09-27: Người dùng trả lời 4 câu hỏi của Phase 15b: làm **cả Đợt 1 lẫn Đợt 2** (và Đợt 3–4) trước khi phát hành 0.1.1; đồng ý thêm trường tên file gốc vào `messages.jsonl` ("Đã chốt" mục 8, bổ sung mục 3, không đổi D1–D9); đồng ý chặn hai tiến trình chung session; cặp restore mất thư mục thì cho **chạy lại từ đầu hoặc cập nhật đường dẫn**. Kế hoạch từng mục ghi ở "Phase 15b" → "Kế hoạch thực hiện" để các phiên sau bắt đầu thẳng. - 2026-09-27: **Phase 15b bắt đầu, phạm vi mở rộng** theo yêu cầu người dùng: từ "chỉ diff của Phase 15a" thành **toàn bộ dự án**, là lần hardening cuối trước phát hành (Phase 16). Không đổi D1–D9. Review xong cùng ngày, chưa sửa code; phát hiện, giải pháp, kế hoạch 4 đợt và 4 câu hỏi cho người dùng ở "Phase 15b". - 2026-09-27: Người dùng xác nhận **Phase 15a chạy đúng trên terminal thật**, và yêu cầu thêm **Phase 15b — Hardening** vào lộ trình (chưa làm ngay: chỉ ghi kế hoạch) để rà soát lại code Phase 15a tìm trùng lặp/code luộm thuộm/kiến trúc chưa ổn/bug khác trước khi coi là xong hẳn. Phase cũ "Phase 15" đổi tên thành **Phase 15a** cho khớp (không đổi nội dung, chỉ thêm hậu tố vì giờ có 15b) — không đổi D1–D9. Xem "Phase 15a — ghi chú", "Phase 15b — ghi chú". - 2026-09-27: **Phase 15a xong** (mục "Backup"/"Restore" trong menu full-screen — xem "Phase 15a — ghi chú"). Không đổi D1–D9. Hai phát hiện không lường trước, sửa cùng lúc: (1) `ui/menu/screens/resume.py::ResumeScreen` ("Chạy tiếp"/"Thử lại tin lỗi") dựng `RunScreen` mà chưa từng truyền `reader_override` — một cặp bắt nguồn từ `restore` được tiếp tục qua menu full-screen (thay vì `tgmirror run`/`retry` dòng lệnh) sẽ đọc nhầm gateway sống thay vì thư mục backup; đã vá bằng `reader_override_for(outcome.run.options.from_backup)`, giống hệt cách `cli/commands/run.py`/`retry.py` đã làm cho CLI cổ điển từ Phase 11b. (2) Người dùng chỉ ra sau bản đầu: câu hỏi thư mục trong menu vẫn chỉ là chữ thường, không có Tab gợi ý đường dẫn như wizard cổ điển — thêm `ui/menu/prompter.py::complete_path`/`PathQuestion` và `MenuKey.TAB` để đóng khoảng cách đó (chi tiết ở "Phase 15a — ghi chú"). - 2026-09-27: Thêm **Phase 16 — Phát hành 0.1.1 chính thức** vào lộ trình, "Đồng bộ edit/delete" dời từ 16 thành **17** — không đổi D1–D9 (chỉ thứ tự/đánh số việc làm). Mục đích: đóng tiêu chí bỏ ngỏ của Phase 13 ("chưa thử với một tag thật") bằng một lần phát hành thật, không phải thêm code. Tại thời điểm ghi, tag chưa được push (`git tag` rỗng, `pyproject.toml` vẫn `0.1.0`) — người dùng xác nhận chỉ push khi quyết định phát hành thật, nên phase này có số trong lộ trình nhưng vẫn để `[ ]` chưa xong cho tới khi đó. Xem "Đã chốt" mục 7, "Phase 16 — Phát hành 0.1.1 chính thức". - 2026-09-27: Chốt cách đóng gói/nộp winget cho Phase 14 (chưa bắt đầu code) — không đổi D1–D9 (không phải hành vi tgmirror, chỉ cách đóng gói/phân phối): zip `onedir`, và tự động mở PR vào `microsoft/winget-pkgs` bằng GitHub Action `vedantmgoyal2009/winget-releaser` thay vì tự viết bước `wingetcreate update --submit`. Xem "Đã chốt" mục 6, "Phase 14 — Phát hành đầy đủ". - 2026-09-26: Phase 13 bắt đầu, phạm vi thu hẹp lại thành một lát cắt theo yêu cầu người dùng (CI + khung `release.yml` + đẩy ảnh container), phần còn lại tách thành **Phase 14** riêng (PyInstaller/PyPI/winget/APT-RPM/AUR) để phiên sau — không đổi D1–D9 (không phải quyết định về hành vi tgmirror, chỉ về thứ tự làm việc). Cùng lúc, người dùng yêu cầu "mở rộng phạm vi" sang tự động build và đẩy ảnh vào `docker.io`, đổi kênh container đã ghi trong "Kế hoạch Phase 9–15" (đổi tên từ "Kế hoạch Phase 9–13" cùng ngày, xem bên dưới) từ GHCR sang **Docker Hub** (`docker.io/tamvo1808/tgmirror`) — không dùng cả hai, xem "Đã chốt" mục 5 và "Phase 13 — ghi chú". Sau khi Phase 13 xong (khung release + Docker Hub, chưa thử tag thật), người dùng thêm **Phase 15** vào lộ trình (màn hình TUI full-screen cho `backup`/`restore`, lấp khoảng trống "chưa có mục trong menu full-screen" của Phase 11a) và yêu cầu đổi số: phần hoãn của Phase 13 thành Phase 14, Phase 15 là TUI backup/restore, "Đồng bộ edit/delete" dời từ `14+` thành **16**. Trước đó, Phase 12 (Docker chạy một lần) xong: `cli/interrupt.py::stop_on_interrupt` bắt thêm SIGTERM (trước chỉ SIGINT) để `docker stop` dừng êm giống Ctrl+C, xác nhận bằng Docker thật (script dò tín hiệu chạy làm PID 1, `docker stop` thật) chứ không chỉ test đơn vị; người dùng sau đó xác nhận **"Docker chạy tốt" trên Telegram thật**, chi tiết chưa ghi lại. Xem "Phase 12 — ghi chú", "Phase 13 — ghi chú". - 2026-09-25: Brainstorm và lên kế hoạch Phase 9–13 (keyring, CI/release/winget, Docker, xuất/nhập app data, backup/restore kênh ra đĩa; xem "Kế hoạch Phase 9–13"). Không viết mã, không đổi D1–D9; "Đồng bộ edit/delete" dời thành 14+. Người dùng chốt: **tính năng trước, đóng gói và phân phối cuối cùng** (thứ tự 9 keyring → 10 app data → 11 backup/restore → 12 Docker → 13 phát hành; Linux thêm kho APT/RPM ký GPG và AUR); Docker **chạy một lần** (hỏi lại vì "chạy dưới dạng job" có thể đụng quyết định bỏ job/daemon 2026-09-20 — không đụng); xuất app data **không chứa secret**, đăng nhập lại sau khi nhập. Sau đó người dùng duyệt cả bốn điểm còn mở (xem "Đã chốt" trong mục kế hoạch): restore một backup có lời tuyên bố D3 thì hỏi lại lời tuyên bố và không đọc lại kênh nguồn (cách áp D3 cho đường mới, không đổi nội dung D3); "Mục tiêu" của `00-tong-quan.md` sửa khi Phase 11 bắt đầu; `messages.jsonl` + HTML; winget `tamvcspk.tgmirror`, PyPI thật, kho APT/RPM tự host trên GitHub Pages. Phát hiện khi lập kế hoạch: backup ra đĩa một nguồn `noforwards` là "lưu nội dung" nên D3 áp y như reupload; hiện chỉ SIGINT được bắt nên `docker stop` (SIGTERM) chưa dừng êm. - 2026-09-25: **Tinh chỉnh D3** — người dùng chạy thử menu full-screen thật trên một nguồn `noforwards` mà tài khoản không phải admin, thấy màn hình cứ hỏi lại đích (đúng như "một bước lỗi thì hỏi lại chính bước đó" đã thiết kế) vì trước đây chỉ có cờ dòng lệnh mới vượt qua được D3 cho tài khoản không phải admin, mà menu không có chỗ gõ cờ. Hỏi lại người dùng trước khi đổi (D3 là D1–D9): người dùng chốt đây không phải đảo ngược nội dung quyết định (vẫn phải là lời tuyên bố cố ý của chính user), chỉ thêm một cách nhập nó trong flow tương tác — ban đầu đề xuất một câu Có/Không, người dùng yêu cầu đổi thành **gõ nguyên văn đúng chữ cờ** (`--yes-i-administer-this-channel`) vào một câu hỏi riêng, Esc để thoát, gõ gì khác thì coi như từ chối — giữ đúng mức độ "cố ý" như gõ trên dòng lệnh thay vì một cú bấm chuột/phím dễ dàng. Cài ở `cli/commands/clone.py::CloneFlow._confirm_unadministered`, dùng chung cho cả wizard cổ điển lẫn menu (cùng `CloneFlow`). Không đổi hành vi không tương tác (vẫn chỉ cờ, từ chối mã 4 như cũ). - 2026-09-25: Review wizard/`clone` và sửa: kiểm lịch sử cặp ngay sau bước đích (từ chối trước các câu chiến lược); nguồn cấm lưu nội dung với mode chỉ forward bị từ chối trước khi tạo đích (trước đây admin được cảnh báo rồi chạy, lần chạy mới thất bại mã 4 và để lại đích rỗng) — hệ quả của D3, không đổi D1–D9; không hỏi gõ cờ D3 khi mode cờ không tải lên lại được; báo `warn.topic_as_hashtag` khi hashtag bật mà không hỏi; wizard hỏi lại từng câu sai (tên kênh, từng tiêu chí filter) thay vì cả nhóm; sửa help `--dst`/`--mode`/`--caption` và nhãn caption cũ. - 2026-09-25: Sửa phase 8 sau review + thử thật: forum → không-phải-forum dưới `auto` giờ gửi lại tin trong topic để mang hashtag (cả khi caption `keep`), không đổi D1–D9 (D3 áp dụng như mọi lần tải lên lại). Xem "Phase 8 — ghi chú", mục `topic_as_hashtag`. - 2026-09-25: Phase 8 xong (group/supergroup/forum, ánh xạ topic, `topic`/`from_user`; xem "Phase 8 — ghi chú"). Không đổi D1–D9. **Đảo "chốt 2026-09-19"**: đích có sẵn không còn phải cùng loại nguồn — người dùng yêu cầu brainstorm thêm giữa lúc duyệt kế hoạch (đưa ra ví dụ clone group→broadcast), chốt ma trận cross-kind mở hoàn toàn cộng cơ chế `topic_as_hashtag`/`_confirm_topic_loss` cho riêng trường hợp forum → không-phải-forum (chi tiết ở "Phase 8 — ghi chú"). Không phải quyết định D1–D9 (không có số D gắn với luật cũ). Việc phát sinh không lường trước, phát hiện khi cài: `mirrors` thiếu cột `dst_kind` (chỉ có `src_kind`) nên `run`/`retry` không dựng lại đúng loại đích cho một cặp cross-kind — thêm migration schema v2 và sửa một bug có sẵn (`cli/commands/run.py::pair_of` dùng nhầm `src_kind` cho đích, vô hại khi luật cũ ép hai bên cùng loại). - 2026-09-24: Phase 7 xong (badge "đang chạy ở nơi khác", `tgmirror doctor`, đóng gói, README) — xem "Phase 7 — ghi chú", đoạn "Phần còn lại của Phase 7 xong". Không đổi D1–D9. Người dùng yêu cầu "bắt đầu phase tiếp theo"; hỏi lại vì Phase 7 vẫn `[ ]` (menu Chặng 1–3 xong nhưng doctor/đóng gói chưa) trong khi Phase 8 chưa bắt đầu — người dùng chọn làm nốt Phase 7. Quyết định nhỏ không phải D1–D9: `doctor` không được thêm vào menu full-screen (chỉ CLI cổ điển), vì mục "Giao diện full-screen (menu)" của `02-cli-ux.md` liệt kê đúng các mục đã có và không nhắc tới doctor — có thể thêm sau nếu cần. Sự cố ngoài dự kiến: lúc xác minh gói cài được (`uv build` + cài vào venv cô lập), lệnh `tgmirror doctor` chạy từ venv đó rơi vào `Paths.default()` (không có `--root`/config test riêng) nên gọi Telegram thật của người dùng (chỉ đọc, không ghi gì) mà không xin phép trước — ghi lại làm bài học, không lặp lại. - 2026-09-24: Chặng 3 của giao diện full-screen (menu) xong: `tgmirror config get`/`set` (chưa tồn tại trước đó) cùng mục "Cấu hình" của menu (xem "Phase 7 — ghi chú", "Chặng 3 — đã làm"). Không đổi D1–D9. Người dùng yêu cầu bắt đầu phase kế tiếp bằng tên tắt "màn hình commit"; hỏi lại vì thuật ngữ đó không có trong tài liệu, xác nhận đây chính là mục "Cấu hình" còn thiếu (mục 3, "Chưa làm, để Chặng 2"). Việc phát sinh không lường trước: hai test có sẵn của `test_cli_app_menu.py` đếm cứng số lần bấm Down để chạm "Thoát", lệch một bậc và treo tới khi `pytest-timeout` giết ở 60 giây thay vì báo lỗi rõ ràng ngay; sửa số lần bấm. Badge "đang chạy ở nơi khác" (mục 4 còn lại của Chặng 1) vẫn chưa làm. - 2026-09-24: Chặng 2 của giao diện full-screen (menu) xong: "Sao chép mới" và "Đăng nhập" trong khung, Esc lùi một câu hỏi (xem "Phase 7 — ghi chú", "Chặng 2 — đã làm"). Không đổi D1–D9; câu hỏi D3 vẫn giữ nguyên (cùng `CloneFlow` với CLI). "Cấu hình" và badge "đang chạy ở nơi khác" chưa làm. - 2026-09-23: Chặng 1 của giao diện full-screen (menu) xong (xem "Phase 7 — ghi chú", mục "Kế hoạch giao diện full-screen (menu)"). Không đổi D1–D9. Người dùng yêu cầu triển khai sau brainstorm; khi hỏi lại cách ghép nối với các lệnh cũ (`Live` không lồng được, `typer.echo` vỡ dưới alt-screen), người dùng chọn vẽ thật sự bên trong khung ngoài thay vì tạm thoát alt-screen gọi lệnh cổ điển — khối lượng lớn hơn nên chia Chặng 1 (khung, điều hướng, màn hình chạy/tiến độ thật, Trạng thái/Lịch sử/Kênh đã join/Tài khoản) và Chặng 2 (MenuPrompter cho "Sao chép mới"/"Đăng nhập", còn lại). Việc phát sinh không lường trước: `cli/commands/run.py`/`retry.py` phải tách `resume_flow`/`retry_flow` khỏi lớp `typer.Exit`/`asyncio.run` để gọi được từ vòng lặp async của app; `cli/keys.py`'s hai reader nền tảng đổi để không còn vứt byte thứ hai của phím mũi tên (không đổi hành vi p/r/q). - 2026-09-23: Brainstorm giao diện full-screen (menu) thay cho gõ lệnh (xem "Phase 7 — ghi chú", mục "Kế hoạch giao diện full-screen (menu)"). Không đổi D1–D9, không viết mã. Người dùng chốt hai điểm khi được hỏi: gõ trơn `tgmirror` có terminal thật thì vào thẳng app (kiểu Norton Commander/Symantec Ghost), Ctrl+C giữa một run luôn dừng **và** thoát hẳn (không lùi về menu). Còn lại là ý tưởng, chưa duyệt để bắt đầu code. - 2026-09-23: `tgmirror run` không số, có terminal, và lịch sử có hơn một cặp thì hỏi chạy tiếp cặp nào (`wizard.pick_run`, `Store.list_pairs`), thay vì luôn âm thầm lấy lần chạy mới nhất toàn hệ thống — một cặp hoặc không terminal thì vẫn tự động như cũ, không hỏi. Không phải D1–D9. Người dùng yêu cầu sau khi hỏi về flow: nhận ra không có cách chọn cặp khi gõ `run` trơn nếu có nhiều cặp, phải nhớ số run từ `history`. - 2026-09-23: Phần TUI của phase 7 xong (xem "Phase 7 — ghi chú"). Không đổi D1–D9. Người dùng yêu cầu bắt đầu (đã hỏi lại phạm vi: làm trọn Rich TUI theo đúng roadmap, không phải một công cụ nhỏ chỉ để test tay). Việc phát sinh không lường trước: `Runtime.interactive` không đủ để chọn TUI vì test wizard mượn cờ đó cho một `CliRunner` không phải terminal thật; giải quyết bằng `Runtime.reporter` (tách giống `Runtime.keys` đã làm). - 2026-09-20: Đợt tăng tốc và tiến độ (Phase 6b, xem "Phase 6b — ghi chú"). Không đổi D1–D9. **Đảo lại một lựa chọn của phase 6**: "chỉ pipeline tải trước, không nhiều kết nối kiểu FastTelethon" (ghi cùng ngày) — người dùng nay chọn có nhiều request/kết nối trong một ngân sách chung, vì đã hiểu chi phí (API private của Telethon, khó kiểm bằng fake, chờ số đo); skill `telethon-engine` sửa theo. Người dùng chốt: analyze chỉ đếm (mặc định), không IPC, nhiều file cùng lúc miễn không vượt trần request (dùng theo dung lượng), tải nhanh hơn gửi phải có trần cứng, cho phép spike. Đợt này làm phần rủi ro thấp (đếm, tiến độ, trần tải trước, script spike); đổi pace/write-ahead và bộ lập lịch request chờ duyệt riêng và số đo. - 2026-09-20: **Đổi D3.** Trước: nguồn `noforwards` mà tài khoản không phải admin thì từ chối bất kể cờ; admin thì `--mode reupload` kèm xác nhận. Sau: mặc định vẫn tôn trọng `noforwards`, nhưng user có thể tự tuyên bố và **chịu hoàn toàn trách nhiệm** bằng `--mode reupload --yes-i-administer-this-channel`, và cờ này cho qua **cả tài khoản không phải admin** (lý do của user: chủ kênh thường có nhiều tài khoản, tài khoản đang chạy tgmirror có thể không phải cái đứng tên admin). Đi kèm: mỗi lần chạy dựa trên lời tuyên bố in `warn.responsibility`; `--yes` vẫn không thay được cờ; câu hỏi tương tác vẫn chỉ cho tài khoản là admin; tgmirror không kiểm tra được quyền sở hữu và nói rõ điều đó; lời tuyên bố (`RunOptions.protected_ack`) theo cả cặp, `run`/`retry` dùng lại. CLAUDE.md luật 5, `docs/00`, `01`, `02` và các skill đã sửa theo. Người dùng yêu cầu đổi (không phải suy diễn của Claude). - 2026-09-20: Phase 6 xong (chiến lược B: reupload, `--caption`, tin đặc thù, tải trước). Không đổi D1–D9; D3 được cài đặt đúng chữ ("kèm xác nhận"): xác nhận là câu hỏi hoặc `--yes-i-administer-this-channel`, `--yes` không thay được. Người dùng chọn phạm vi (đủ theo lộ trình) và chọn pipeline tải trước thay cho uploader nhiều kết nối, trước khi viết mã. Đổi so với thiết kế cũ: bỏ `core/uploader.py` và `[limits] upload_concurrency` (thay bằng `prefetch`, `tmp_budget_mb`); tin không hỗ trợ dừng lần chạy thay vì hỏi ở bước xem trước; chưa có delay theo dung lượng. Các lựa chọn nhỏ và hai lỗi đã sửa ghi ở "Phase 6 — ghi chú". - 2026-09-20: Phase 5 xong (`retry`, `status`). Không đổi D1–D9, không đổi schema. Các lựa chọn nhỏ và một lỗi mất-tin-lỗi đã sửa ghi ở "Phase 5 — ghi chú". Người dùng yêu cầu bắt đầu phase 5 theo lộ trình; các chi tiết thiết kế (retry là một lần chạy, `status` chỉ đọc DB, tin đã xóa thành `skipped`) chưa được duyệt riêng: đổi được nếu người dùng muốn khác. - 2026-09-20: Thêm `--fresh` (xem "`--fresh` — làm lại từ đầu"): cờ trên `clone`/`run`, chỉ quên tiến độ, có câu hỏi hàng rào khi đích có thể bị trùng; không phải D1–D9, người dùng đã duyệt kế hoạch trước khi viết mã. - 2026-09-20: Bỏ khái niệm job (xem "Tái thiết luồng job"). `clone` chạy ngay trong foreground; chỉ lưu nhật ký các lần chạy (`runs`) cộng một điểm kiểm tra ẩn theo cặp (`mirrors`); chạy lại cùng cặp là delta, filter được nhớ; `run`/`pause`/`stop` giữ nhưng nhắm vào lần chạy; pause giữ tại chỗ; phím `p`/`r`/`q`. D5 (một file SQLite) giữ nguyên, chỉ đổi lý do ("`tgmirror jobs` đơn giản" → "`tgmirror history` đơn giản"). Không viết migration từ `jobs` (dự án đang phát triển, người dùng chọn xóa DB cũ). Đảo ngược quyết định "mỗi cặp một job, cặp đã có job thì mã 2" (commit 9ed8509): cùng một cặp giờ là trường hợp delta. Người dùng đã duyệt kế hoạch trước khi viết mã. - 2026-09-19: Đổi tên dự án `twingram` → **tgmirror** (package `tgmirror`, lệnh `tgmirror`, DB `tgmirror.db`, biến môi trường `TGMIRROR_API_ID`/`TGMIRROR_API_HASH`), vì `twingram` đã bị chiếm trên PyPI/GitHub. Lệnh `twin` bỏ hẳn, không giữ alias. - 2026-09-19: Mở rộng phạm vi v1 từ "chỉ broadcast" sang mọi loại nguồn (broadcast, supergroup, group, forum) kèm ánh xạ topic; thành phase 8. Không phải D1–D9 nhưng đổi danh sách "không phải mục tiêu". Ngược lại chốt **không** làm daemon và **không** làm multi-account. - 2026-09-19: Chốt: đích có sẵn phải cùng loại nguồn; không thêm tên người gửi; có cờ `--placeholder` gửi tin text thay thế cho tin bị bỏ vì không hỗ trợ. - 2026-09-19: Chốt xử lý tin đặc thù cho chiến lược B: poll/quiz/location/contact giữ (poll mất vote, opt-in), game/invoice bỏ + cảnh báo. Thêm trạng thái `msg_map.status='skipped'`. Đoạn code mẫu trong ghi chú nguồn (`PollAnswerSyntax`, tự lắp `InputMediaPoll`) **không dùng**: `PollAnswerSyntax` không tồn tại trong Telethon 1.45; dùng `send_message(file=message.media)`. - 2026-09-20: Phase 4 xong. Không đổi D1–D9 (D6 vẫn là `flood_sleep_threshold=0`, mọi FloodWait vào limiter của mình). Thêm khóa `[limits] read_delay` và cờ `run --wait` (`--wait` đã có trong thiết kế ở `05-chong-flood.md`); các lựa chọn nhỏ ghi ở "Phase 4 — ghi chú". - 2026-09-20: Phase 3 xong. Không đổi D1–D9. Thêm dependency `pyyaml` và `regex`. Các lựa chọn nhỏ ghi ở "Phase 3 — ghi chú" và `03-filters.md`: `date` nửa mở, thiếu thuộc tính thì predicate sai, không đẩy `contains`, `--refilter` là cách đổi filter. - 2026-09-20: Phase 2 xong. Không đổi D1–D9. Các lựa chọn nhỏ ghi ở "Phase 2 — ghi chú": limiter tạm thời, FloodWait dừng job thay vì chờ (cho tới phase 4), một job cho mỗi cặp nguồn/đích, `run` chạy được với job `done`, `last_message_id` vào protocol. - 2026-09-19: Thêm skill `doc-sync` và luật "mỗi task đều xét cập nhật docs/skills" (CLAUDE.md, luật 9). - 2026-09-19: Bản thiết kế đầu tiên. D3 đổi so với brainstorm ban đầu (brainstorm cho phép reupload cho mọi kênh `noforwards`; bản này tôn trọng cài đặt bảo vệ nội dung của chủ kênh).