# 04 — State, checkpoint, delta Một file SQLite (`WAL` mode, `foreign_keys=ON`, `busy_timeout=5000` để `pause`/`stop` từ process khác không bị lỗi khóa). Phiên bản schema nằm ở `PRAGMA user_version`; `store/schema.sql` là phiên bản 1, các thay đổi sau thêm migration đánh số đăng ký ở `store/db.py::default_migrations` (mỗi migration chạy trong một transaction, có test nâng cấp từ phiên bản trước). Phiên bản 2 (phase 8, 2026-09-25): thêm `mirrors.dst_kind`, backfill từ `src_kind` cho các cặp có sẵn. Phiên bản 3 (phase 11a, 2026-09-25): thêm bảng `backups` và cột `flood_log.backup_id` (xem "Backup (Phase 11a)" bên dưới). Phiên bản 4 (phase 19d1, 2026-10-15): thêm `flood_log.dst/action/sent_1h/sent_24h/premium` và hai bảng `limiter_lanes`, `sent_hours` (từ v6 là `sent_buckets`; xem `05-chong-flood.md`, "Làn"). Phiên bản 5 (phase 19d2, 2026-10-15): `limiter_lanes` thêm `budget`, `window_hours`, `budget_since`, `flood_at`, `flood_seconds` (ngân sách học được của làn, `NULL` = chưa học). Phiên bản 6 (phase 19d2, 2026-10-17): `sent_hours` đổi tên thành `sent_buckets` và cột `hour` thành `bucket` (ô 5 phút thay vì 1 giờ); mỗi giờ cũ chuyển thành ô cuối của nó (`hour × 12 + 11`), để cửa sổ không bao giờ nhả những tin đó sớm. Phiên bản 7 (phase 19d4, 2026-10-17): `limiter_lanes` thêm `ok_amount`, `bad_amount`, `bad_at`, `checked_at`, `probe_fails` (hai phía của giới hạn đã học; xem `05-chong-flood.md`, "Thăm dò giới hạn"); ngân sách đã học trước đó được điền `ok_amount = budget`, `bad_amount = budget × 5 / 4` (chia nguyên: 1506 ra đúng 1882 của lần chạy 68), `bad_at = flood_at`, `checked_at = budget_since`. ## Hai thứ, chỉ một thứ người dùng thấy | | Là gì | Người dùng thấy | |---|---|---| | **Run** (bảng `runs`) | Một lần thực thi `clone`/`run`: lúc bắt đầu/kết thúc, trạng thái, bộ đếm của riêng lần đó, filter đã dùng, lỗi, cờ `control`, heartbeat. **Đây là nhật ký.** | Có: `tgmirror history` | | **Mirror** (bảng `mirrors`) | Điểm kiểm tra của một cặp nguồn → đích: con trỏ `cursor_src_id`, filter đang nhớ, `dst_base_id`. `msg_map` treo vào nó | **Không**: không có id, tên, không bao giờ được liệt kê hay sửa | Vì sao phải giữ trạng thái theo cặp: delta cần con trỏ, chống crash cần các hàng `msg_map` ghi trước (write-ahead) và `dst_base_id` để reconcile, và không thứ nào suy ra được từ nhật ký mà không quét lại cả hai kênh. Nên "không lưu job" nghĩa là không có thực thể để người dùng quản lý, không phải không có trạng thái. Mirror được tạo ở lần `clone` đầu tiên của cặp. ## Schema ```sql CREATE TABLE mirrors ( -- điểm kiểm tra của một cặp nguồn/đích id INTEGER PRIMARY KEY, account TEXT NOT NULL, -- tên session src_id INTEGER NOT NULL, -- peer id nguồn src_title TEXT, src_kind TEXT NOT NULL, -- broadcast|supergroup|forum|group dst_id INTEGER NOT NULL, dst_title TEXT, dst_kind TEXT NOT NULL, -- v2 (phase 8): không còn ép phải bằng src_kind mode TEXT NOT NULL, -- auto|copy|reupload (của lần tạo) filters_json TEXT NOT NULL, -- filter đang nhớ ({} = không lọc) options_json TEXT NOT NULL, -- dst_base_id (xem dưới); key lạ bị bỏ qua cursor_src_id INTEGER NOT NULL DEFAULT 0, -- id nguồn lớn nhất đã xử lý xong (done/failed/filter-skip) created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE UNIQUE INDEX mirrors_pair ON mirrors(src_id, dst_id); CREATE TABLE runs ( -- nhật ký: một dòng cho mỗi lần chạy id INTEGER PRIMARY KEY, mirror_id INTEGER NOT NULL REFERENCES mirrors(id) ON DELETE CASCADE, mode TEXT NOT NULL, filters_json TEXT NOT NULL, -- filter lần này dùng options_json TEXT NOT NULL, -- batch_size, dst_base_id, pushdown status TEXT NOT NULL, -- running|paused|stopped|waiting_flood|done|failed control TEXT NOT NULL DEFAULT 'none',-- none|pause|stop (do CLI đặt, runner đọc) cursor_from INTEGER NOT NULL DEFAULT 0, -- nơi lần này bắt đầu đọc nguồn cursor_to INTEGER NOT NULL DEFAULT 0, -- lần này đi tới đâu resume_at TEXT, -- khi waiting_flood fail_reason TEXT, -- lỗi, hoặc daily_cap / interrupted / taken_over stats_json TEXT NOT NULL DEFAULT '{}', -- done, failed, skipped_filter, already_done, ... của RIÊNG lần này started_at TEXT NOT NULL, ended_at TEXT, updated_at TEXT NOT NULL -- đồng thời là heartbeat khi đang chạy ); CREATE TABLE msg_map ( mirror_id INTEGER NOT NULL REFERENCES mirrors(id) ON DELETE CASCADE, src_msg_id INTEGER NOT NULL, dst_msg_id INTEGER, -- NULL nếu pending/failed grouped_id INTEGER, src_topic_id INTEGER, -- NULL nếu nguồn không phải forum status TEXT NOT NULL, -- pending|done|failed|skipped reason TEXT, -- lý do lỗi/bỏ qua; hàng `pending` từng lỗi giữ lý do cũ (xem "Hủy pending") batch_id INTEGER, run_id INTEGER, -- lần chạy đã kết thúc hàng này gần nhất (để `history n`/`retry n` liệt kê tin lỗi) ts TEXT NOT NULL, PRIMARY KEY (mirror_id, src_msg_id) ); CREATE INDEX msg_map_status ON msg_map(mirror_id, status); CREATE INDEX msg_map_run ON msg_map(run_id, status); CREATE TABLE topic_map ( -- chỉ cặp forum mirror_id INTEGER NOT NULL REFERENCES mirrors(id) ON DELETE CASCADE, src_topic_id INTEGER NOT NULL, -- id tin gốc của topic (General = 1) dst_topic_id INTEGER NOT NULL, title TEXT, PRIMARY KEY (mirror_id, src_topic_id) ); CREATE TABLE flood_log ( id INTEGER PRIMARY KEY, run_id INTEGER, backup_id INTEGER, -- v3: loại trừ lẫn nhau với run_id (xem "Backup") ts TEXT NOT NULL, kind TEXT NOT NULL, -- flood_wait|slow_mode|premium_wait|transport_429|peer_flood seconds INTEGER, method TEXT, delay_ms INTEGER, -- delay của làn tại thời điểm đó (trước khi tăng) batch_size INTEGER, action TEXT, -- v4: làn: forward|send|history|file (NULL = hàng cũ) dst INTEGER, -- v4: đích của làn ghi (NULL cho làn đọc) sent_1h INTEGER, -- v4: tin làn ghi đã gửi trong 1 giờ qua (ô 5 phút) sent_24h INTEGER, -- v4: ... trong 24 giờ qua premium INTEGER -- v4: tài khoản có Premium (NULL = không biết) ); CREATE TABLE backups ( -- v3 (phase 11a): nhật ký backup, không có mirror/msg_map id INTEGER PRIMARY KEY, account TEXT NOT NULL, src_id INTEGER NOT NULL, src_title TEXT, src_kind TEXT NOT NULL, dir TEXT NOT NULL, -- thư mục backup, là "định danh" thay cho mirror filters_json TEXT NOT NULL, status TEXT NOT NULL, -- như runs.status control TEXT NOT NULL DEFAULT 'none', cursor_to INTEGER NOT NULL DEFAULT 0, -- chỉ để hiển thị: xem "Backup" bên dưới resume_at TEXT, fail_reason TEXT, stats_json TEXT NOT NULL DEFAULT '{}', started_at TEXT NOT NULL, ended_at TEXT, updated_at TEXT NOT NULL ); CREATE INDEX backups_dir ON backups(dir); CREATE TABLE limiter_state ( -- persist AIMD giữa các lần chạy account TEXT PRIMARY KEY, delay_ms INTEGER NOT NULL, -- v4: delay cao nhất của các làn ghi day TEXT NOT NULL, -- YYYY-MM-DD (local) sent_today INTEGER NOT NULL, updated_at TEXT NOT NULL ); CREATE TABLE limiter_lanes ( -- v4: delay AIMD riêng của từng làn account TEXT NOT NULL, action TEXT NOT NULL, -- forward|send (ghi), history|file (đọc) dst INTEGER NOT NULL, -- đích của làn ghi; 0 cho làn đọc delay_ms INTEGER NOT NULL, budget INTEGER, -- v5: tin/cửa sổ; NULL = chưa gặp flood dài, không chặn window_hours INTEGER, -- v5: 1 hoặc 24 budget_since TEXT, -- v5: lần đổi cuối (cắt hay tăng 10%): đồng hồ tăng trưởng flood_at TEXT, -- v5: flood dài đã đặt/cắt nó flood_seconds INTEGER, ok_amount INTEGER, -- v7: mức cao nhất đã chạy sạch một cửa sổ bad_amount INTEGER, -- v7: mức thấp nhất từng gây flood dài bad_at TEXT, -- v7: lần cuối gây flood; quá `probe_after_hours` thì `bad` hết chặn tăng trưởng checked_at TEXT, -- v7: lần cuối giới hạn được đem ra thử probe_fails INTEGER NOT NULL DEFAULT 0, -- v7: thăm dò hỏng (chưa có gì ghi nó) PRIMARY KEY (account, action, dst) ); CREATE TABLE sent_buckets ( -- v4 (tên cũ sent_hours, theo giờ), v6: tin mỗi làn ghi đã gửi theo ô 5 phút, giữ 24 giờ account TEXT NOT NULL, action TEXT NOT NULL, dst INTEGER NOT NULL, bucket INTEGER NOT NULL, -- unix time // 300 (v4: cột `hour`, // 3600) sent INTEGER NOT NULL, PRIMARY KEY (account, action, dst, bucket) ); ``` **Không có migration từ mô hình job cũ** (2026-09-20): dự án chưa phát hành nên schema `runs` + `mirrors` được gộp thẳng vào `schema.sql` (phiên bản 1) thay cho bảng `jobs`; cơ sở dữ liệu cũ được xóa (`tgmirror.db`), không chuyển đổi. Hệ quả: một cặp đã clone bằng bản cũ mà DB bị xóa thì lần `clone` đầu tiên coi như cặp mới, nên nếu kênh đích còn các bản sao cũ, tin sẽ bị sao chép trùng; dùng đích mới hoặc dọn đích trước. Từ khi phát hành, mọi thay đổi schema phải là migration đánh số có test nâng cấp. `options_json.dst_base_id`: id tin mới nhất của kênh đích lúc clone cặp lần đầu (`gateway.last_message_id`, chỉ gọi khi cặp mới). Mirror lưu một lần; mỗi run chép giá trị vào `runs.options_json`. Reconcile chỉ đọc đích sau `max(dst_msg_id của các hàng done, dst_base_id)`. `options_json.src_last_id` (ghi ở `runs`, không ở `mirrors`; 0 = không biết): id tin mới nhất của nguồn lúc lần chạy bắt đầu (`begin_run` đọc bằng `last_message_id`, một request ở bước chuẩn bị), là tổng mà `status` đo tiến độ và ETA (`engine/status.py`); tin đăng thêm trong lúc chạy không nằm trong đó. `options_json.retry_of` (ghi ở `runs`): id lần chạy mà lần này gửi lại các tin `failed` (xem "Retry"); `None` là lần chạy thường. Hai khóa này chỉ thuộc về từng lần chạy: `RunOptions.for_pair` bỏ chúng khi ghi `mirrors.options_json`, và `tgmirror run` không thừa hưởng `retry_of` của lần chạy trước. `options_json` cho chiến lược B (phase 6, ghi ở `runs` và nhớ ở mirror như `batch_size`; `tgmirror run`/`retry` dùng lại giá trị của lần trước): `caption` (`keep|strip-links|append|none`), `caption_text`, `reset_polls`, `ignore_unsupported`, `placeholder`, và `protected_ack` (user đã xác nhận D3 cho nguồn cấm lưu nội dung, xem `01-kien-truc.md`, "Kiểm lại nguồn khi chạy lại"). Lần chạy cũ không có các khóa này được đọc như mặc định (`keep`, tất cả cờ tắt). **Phase 19a** thêm `transform_json` (dạng chuẩn của `engine/transform.py::Transform`, `""` = không có; mirror nhớ như `caption`): danh sách thao tác caption áp *sau* `caption`/`caption_text` (hai thứ không đi cùng nhau, `begin_run` từ chối). Khóa mới trong JSON nên không cần migration; run cũ đọc như không có transform. `options_json.pushdown` (mặc định `true`, ghi ở `runs`): `false` thì đọc mọi tin sau cursor và chỉ lọc ở máy (`clone --no-pushdown`, xem `03-filters.md`). `batch_size` cũng là của từng lần chạy (`tgmirror run` dùng lại giá trị của lần trước). `mirrors.filters_json` / `runs.filters_json`: JSON chuẩn hóa của `FilterSpec` (`{}` = không lọc), nạp lại bằng `FilterSpec.from_json` mỗi lần chạy; hỏng thì lần chạy `failed` với lý do `FilterError: ...`. Mirror giữ filter đang nhớ, run ghi filter lần đó dùng. Tin bị **filter loại** không được ghi vào `msg_map` (hàng triệu hàng vô ích); chỉ tăng bộ đếm `stats.skipped_filter` của lần chạy (đếm theo tin, album tính đủ mọi tin) và đẩy `cursor_src_id` tiến lên. Số đếm và con trỏ đi cùng transaction với batch mà chúng được cộng vào (`commit_batch(extra_stats=...)`), hoặc riêng một transaction `advance_cursor(extra_stats=...)` khi batch không có gì để gửi (chỉ có tin bị loại, hoặc mọi unit đã `done`); không bao giờ vượt qua một unit chưa xử lý. Khi Telegram thu hẹp theo nội dung (`media`/`search`) thì tin bị loại ở server không được thấy nên không được đếm và con trỏ chỉ tới unit khớp cuối cùng; lần chạy sau đọc lại từ đó (rẻ, vì vẫn thu hẹp). Tin **không hỗ trợ** (game, invoice, quiz chưa trả lời, poll khi thiếu `--reset-polls`; xem `01-kien-truc.md`) khác filter: người dùng muốn clone nhưng không thể, nên có ghi `msg_map` với `status='skipped'` + `reason='unsupported:'` và tăng `skipped_unsupported`. `retry` chỉ thử lại `failed`, không thử `skipped`. Hàng `skipped` của tin không hỗ trợ có `dst_msg_id` nếu đã đăng tin text thay thế (`--placeholder`); con trỏ đi qua nó như một tin đã xử lý xong, và bộ đếm là `stats.skipped_unsupported` của lần chạy (`commit_batch` đếm mọi kết quả `skipped`). Tin bị bỏ mà không cần gọi Telegram (poll không có `--reset-polls`, hay `--ignore-unsupported`) vẫn đi qua write-ahead rồi commit trong hai transaction liền nhau (`begin_batch` + `commit_batch`, không có lời gọi Telegram ở giữa): một crash ở giữa chỉ để lại hàng `pending` mà reconcile thấy không có gì ở đích và xóa. Cũng `skipped` là tin mà `retry` thấy đã bị xóa ở nguồn: `reason='gone_from_source'`, tăng `stats.gone` của lần retry (`Store.mark_gone`). `topic_map` (phase 8, `engine/topics.py::TopicResolver`, tạo topic kiểu lười khi tin đầu tiên của nó xuất hiện): gọi `create_topic` rồi lưu `topic_map` ngay sau, không có gì chen giữa — không phải một transaction SQL thật sự bọc quanh lời gọi Telegram (quy tắc transaction bên dưới cấm điều đó), nên một crash đúng giữa hai bước đó không để lại gì sai: từ Phase 19b topic đích được tìm **theo tên** trong các topic đang có của đích trước khi tạo (`TopicResolver._topic_titled`, đọc một lần mỗi lần chạy), lần chạy sau thấy topic đã tạo và dùng lại thay vì tạo trùng. Định tuyến theo hashtag (Phase 19b) không ghi gì vào `topic_map` (khóa của nó là id topic nguồn, hashtag không có): đích chính là nguồn sự thật, tìm lại theo tên mỗi lần chạy. `msg_map.src_topic_id` được ghi theo từng tin (từ `SrcMessage.topic_id`) trong cùng write-ahead của batch; `NULL` khi nguồn không phải forum, hoặc khi tin đó ở General (Telethon không gắn `reply_to` cho tin General, `01-kien-truc.md`). ## Quy tắc transaction Các phương thức của `Store` nhận `run_id` (lần chạy đang làm việc) và tự tìm mirror của nó; thao tác nào chạm `msg_map`/con trỏ thì tác động lên mirror, còn bộ đếm và trạng thái thì lên run. 1. **Trước** khi gọi Telegram cho một batch: `INSERT msg_map(... status='pending', batch_id, run_id)` (write-ahead), commit. 2. **Sau** khi Telegram trả kết quả: trong **một transaction** — cập nhật các hàng thành `done` (kèm `dst_msg_id`) hoặc `failed` (kèm `reason`), cập nhật `mirrors.cursor_src_id`, `runs.cursor_to`, `runs.stats_json`, `updated_at`, `limiter_state` (`commit_batch(limiter=...)`: `sent_today` đi cùng các tin nó đếm; sau một flood `limiter_state` được lưu ngay bằng `save_limiter_state`; hàng theo `mirrors.account`, dùng chung cho mọi cặp của account). Batch được reconcile xác nhận (`confirm_pending`) không cộng vào `sent_today`: đếm hụt tối đa một batch sau một lần crash, chấp nhận được vì cap là ngân sách mềm. 3. `cursor_src_id` chỉ tiến (`MAX(cursor_src_id, ?)` trong SQL), và chỉ tiến tới id lớn nhất của batch đã kết thúc hoàn toàn (không còn `pending`; `commit_batch` từ chối nếu còn hàng `pending` nào khác). Ngoại lệ **duy nhất**, cả hai nằm trong `Store.start_run`: đặt lại về 0 khi filter đổi (xem "Filter khi chạy lại") và khi làm lại từ đầu (xem "Làm lại từ đầu"). Kết quả của một lời gọi copy: - Lời gọi trả về bình thường: từng id có `dst_id` → `done`; id `None` (Telegram không tạo tin, thường vì đã xóa ở nguồn) → `failed` với `reason='not_copied'`. - `PerMessage` (Telegram từ chối chính các id, không tạo gì): xóa `pending` của batch, gửi lại **từng unit một** (mỗi unit là một batch nhỏ có write-ahead và commit riêng). Unit đơn lẻ vẫn bị từ chối → cả unit `failed` với lý do đó. - `FloodWait` ngắn hơn `max_auto_wait`: chờ rồi gửi lại **đúng lời gọi đó**; `pending` giữ nguyên trong lúc chờ (Telegram từ chối nên chưa tạo gì; nếu process chết lúc đó thì reconcile lần sau thấy đích không có gì và gửi lại). `FloodWait` quá dài hoặc quá nhiều lần, `PeerFlood`, `NoPermission`, `ForwardsRestricted`, lỗi RPC khác, hoặc stop/Ctrl+C trong lúc chờ: Telegram chưa tạo gì → xóa `pending` của batch rồi kết thúc lần chạy (xem `01-kien-truc.md`, `05-chong-flood.md`). - **Hủy `pending`** (mọi chỗ trên nói "xóa `pending`": `discard_batch`, `discard_pending`): hàng `pending` chưa từng lỗi thì bị xóa, vì con trỏ sẽ đưa tin đó trở lại. Hàng từng `failed` (write-ahead giữ lại `reason` và `run_id` cũ của nó, xem `msgmap.insert_pending`) thì quay về `failed` với lý do và lần chạy cũ, **không** bị xóa: nó nằm dưới con trỏ, không ai đọc lại, nên xóa là mất dấu hẳn một tin chưa được sao chép. Đây là chỗ `retry` khác lần chạy thường (lỗi được phát hiện khi viết test kill giữa chừng cho retry). `run_id` chỉ chuyển sang lần chạy mới khi batch kết thúc (`finish_batch`) hoặc được reconcile xác nhận. - Chiến lược B: mỗi unit là một batch (`Batch.strategy = REUPLOAD`), nên `pending` của nó là đúng một unit và reconcile so được số tin, loại media và cấu trúc album như thường. `prepare` (đọc và tải) xảy ra **trước** write-ahead nên lỗi ở đó (`PerMessage`: tin đã xóa, loại không dựng lại được) không để lại `pending`: unit được ghi `failed` ngay (`begin_batch` + `commit_batch`). Sau khi upload thành công mà chưa commit thì kết quả như `Transient`: reconcile lần sau tìm bản sao ở đích. **Đẩy byte tách khỏi đăng tin (2026-09-20, người dùng duyệt)**: với unit là một tài liệu/video lớn, gateway `upload_prepared` đẩy byte lên **trước** (không tạo tin nào, nên chưa có `pending`; Telegram bỏ file đã đẩy mà không được đăng), rồi `pace` (thời gian đẩy byte được trừ vào khoảng cách, xem `05-chong-flood.md`), rồi write-ahead, rồi `send_prepared` chỉ *đăng* (một lời gọi ngắn), rồi `commit_batch`. Hệ quả cho crash-safety: cửa sổ `pending` của unit chỉ còn đúng lời gọi đăng; kill lúc đang đẩy byte **không để lại gì để reconcile** (lần sau đẩy lại từ đầu); quy tắc "không lời gọi nào tạo tin trước write-ahead" vẫn đúng vì chỉ lời gọi đăng tạo tin. `FloodWait` khi đẩy byte lặp lại `upload_prepared` (không có `pending`); `FloodWait` khi đăng lặp lại đúng lời gọi `send_prepared` với cùng file đã đẩy (không đẩy lại, không tải lại). Album, file nhỏ và unit không có file không đẩy trước được: `upload_prepared` trả nguyên unit và `send_prepared` làm tất cả như cũ. - Ngân sách của làn (`BudgetReached`, trước 19d2 là `DailyCapReached` với mốc 00:00) xảy ra **trước** write-ahead (ở `limiter.acquire`), và với unit đẩy byte trước thì được kiểm **trước cả khi đẩy** (`Limiter.check_budget`, không tiêu thụ gì) để khỏi đẩy xong mới biết hết ngân sách, nên không có gì để xóa: lần chạy `waiting_flood`, `fail_reason='daily_cap'` (giữ tên cũ), `resume_at` = lúc cửa sổ trượt nhả đủ chỗ cho batch đó. - `Transient` (kết nối đứt sau khi gửi): kết quả **không rõ** → giữ nguyên `pending`, lần chạy `failed('transient')`; lần chạy sau reconcile. ## Resume và delta Cả hai là cùng một đường code: `tgmirror clone` (cùng cặp) hoặc `tgmirror run` mở một run mới trên mirror có sẵn (`Store.start_run`), rồi: 1. Nếu có hàng `pending` (lần trước chết giữa lời gọi) → **reconcile** (`engine/reconcile.py` quyết định, `engine/runner.py` đọc và ghi): - Đọc lại các tin nguồn đang `pending` (một lần quét ngắn từ `min(pending) - 1`) để biết loại media và cấu trúc album. Với một restore (Phase 11b), đây là nơi duy nhất đọc *nguồn* có thể khác gateway thật: `Runner._reader` (đọc nguồn) là `reader_override` khi có, `Runner._dst_reader` (đọc đuôi đích, dòng dưới) luôn là gateway thật — hai reader riêng, vì phía nguồn của một restore không biết đọc một kênh Telegram thật. - Đọc đuôi kênh đích: các tin không phải service có id > `max(dst_msg_id của các hàng done, options.dst_base_id)`. - Số tin, loại media từng tin và cấu trúc album (tin nào cùng album, đánh số theo lần xuất hiện đầu; `grouped_id` ở đích là mới nên không so trực tiếp) đều khớp với batch `pending` → coi là đã gửi, gán `dst_msg_id` theo thứ tự, đánh `done` và đẩy `cursor_src_id` (một transaction). - Không có tin mới ở đích → xóa `pending`, gửi lại batch. - Mơ hồ (đích có tin mới nhưng không khớp, hoặc một tin `pending` đã biến mất khỏi nguồn nên không so được) → cảnh báo người dùng, xóa `pending` và gửi lại (ưu tiên "không sót" hơn "không trùng"), nên đích có thể có vài tin trùng. 2. Lặp lại `iter_messages(src, min_id=cursor_from, reverse=True)` (`cursor_from` = con trỏ của mirror lúc bắt đầu, hoặc 0 khi filter đổi) cùng filter của run (`plan_read`, `03-filters.md`). Không có tin mới → kết thúc nhanh, `done`, mã 0. 3. Bỏ qua bất kỳ unit nào đã có một `src_msg_id` `done` trong `msg_map` (an toàn khi filter đổi và quét lại; một album đã `done` một phần thì phần còn lại là việc của `retry`, không gửi lại cả album). Một batch mà mọi unit đều đã `done` chỉ đẩy `cursor_src_id`, không gọi Telegram, không chờ limiter. Ngữ nghĩa: **at-least-once có reconcile**; trùng lặp chỉ có thể xảy ra ở cửa sổ crash rất hẹp và được phát hiện ở bước 1. Kết quả của mỗi lần chạy nằm ở dòng nhật ký của nó (`history`), còn con trỏ và `msg_map` là của cả cặp, nên số đếm của một lần chạy chỉ gồm tin lần đó làm. ## Filter khi chạy lại `start_run` nhận `filters_json` hoặc `None`: - `None` (không có cờ lọc): dùng filter mirror đang nhớ, con trỏ giữ nguyên → delta. Cặp mới: không lọc. - Giống hệt filter đang nhớ: như `None`. - Khác: **một transaction** thay `mirrors.filters_json`, đặt `cursor_src_id = 0`, rồi mở run với `cursor_from = 0`. `done`/`failed` của `msg_map` giữ nguyên: bước 3 của Resume bỏ qua unit đã `done`, nên không sao chép hai lần; tin `failed` khớp filter mới thì được thử lại. Bộ đếm `skipped_filter` là của từng run nên tự bắt đầu lại. Tin khớp mới được thêm vào cuối kênh đích (thứ tự đích không còn theo thời gian). Từ chối (`RunBusy`) khi cặp đang có run `running`/`paused` với heartbeat còn mới, trước khi đổi gì. ## Làm lại từ đầu `start_run(spec, fresh=True)` (`clone --fresh`, `run --fresh`): trong **cùng một transaction** và **sau** khi kiểm tra cặp có bị giữ (`RunBusy` thì chưa xóa gì), đếm rồi xóa mọi hàng `msg_map` của mirror (mọi trạng thái, kể cả `pending`), đặt `cursor_src_id = 0` và ghi `dst_base_id` mới (tin mới nhất của đích lúc đó, do `begin_run` đọc bằng `last_message_id` — với cặp đã có mirror bình thường không đọc lại) vào `mirrors.options_json`. Lần chạy mới bắt đầu ở `cursor_from = 0`. Filter xử lý như thường (không đưa thì giữ filter đang nhớ). Cặp chưa có mirror thì `fresh` không có gì để quên: coi như lần chạy đầu. `StartedRun.forgot` là số tin `done` đã quên (`None` nếu không phải làm lại). `Store.count_copied(src, dst)` cho CLI đếm trước để hỏi. Các run cũ và bộ đếm của chúng giữ nguyên; danh sách tin lỗi của run cũ (`history n`) mất theo `msg_map`. Reconcile của lần chạy làm lại chỉ đọc đích sau `dst_base_id` mới nên không quét phần đã có từ trước. ## Retry `tgmirror retry [n]` (`RunRequest.retry_of = n`) mở một run mới trên mirror của cặp (`start_run` như mọi lần chạy: cùng kiểm tra `RunBusy`/`check_runnable`, filter và con trỏ giữ nguyên, `cursor_from` = con trỏ hiện tại) với `options.retry_of = n`. Khác lần chạy thường ở nguồn `Unit` của runner (`Runner._failed_units`), còn lại (reconcile trước, gate, `pace`, write-ahead, `commit_batch`, FloodGuard) là cùng một đường: 1. Sau reconcile, chụp danh sách id `failed` của lần chạy `n` (`run_failures(n)`), tăng dần. 2. Đọc theo id, lô 100 (`planner.failed_units`); id không còn ở nguồn → `Store.mark_gone` (`skipped`, không gửi), một transaction cho mỗi lô; idempotent nên crash giữa chừng chỉ làm lô đó được xử lý lại. 3. Gom thành batch như thường; mỗi batch: write-ahead (hàng `failed` → `pending`, giữ lý do/run cũ), `copy_messages`, rồi `commit_batch`: `done` (`dst_msg_id` mới) hoặc `failed` (lý do mới), `run_id` = lần retry. `cursor_src_id` không đổi (`MAX` với id thấp hơn) và `runs.cursor_to` cũng vậy. Crash-safety: kill trước copy → reconcile lần sau thấy đích chưa có tin → hủy `pending` → hàng quay về `failed` (xem "Hủy `pending`") và `retry n` gửi lại; kill sau copy → reconcile tìm thấy bản sao ở đích, ghi `done`. Bị FloodWait quá dài/`PeerFlood`/stop: batch bị hủy, hàng vẫn `failed` của lần `n`. Bộ đếm là của lần retry (`done`: gửi lại được, `failed`: vẫn lỗi, `gone`: đã xóa ở nguồn). Tiến độ của `status` cho retry là `(done + failed + gone) / (đó + số hàng `failed` còn lại của lần `n`)`: hàng đã xử lý chuyển `run_id` sang lần retry nên tự rời khỏi danh sách của `n`. ## Tổng và tiến độ của lần chạy `options_json` của lần chạy thêm khóa `src_protected` (nguồn cấm lưu nội dung theo lần đọc lại của `begin_run`; khi đúng, không gửi bằng mã file, D3) và khóa `total_items` (số tin lần chạy phải xem xét, cận trên, `0` = chưa biết; do `Runner._analyze` ghi bằng `Store.set_total` sau reconcile) và `stats_json` thêm `already_done` (tin vượt qua vì `msg_map` đã có, khi đọc lại từ đầu sau khi đổi filter). Cả hai là của riêng lần chạy: `for_pair` bỏ `total_items`, con trỏ và `msg_map` không đổi, nên **không cần migration**. `Run.handled` là tổng các bộ đếm mà tiến độ dựa vào (xem `01-kien-truc.md`, "Analyze và tiến độ"). Tiến độ truyền file (byte của file đang tải) không lưu: chỉ có trong tiến trình đang chạy. ## Điều khiển Một lần chạy là một tiến trình foreground; điều khiển đến từ ba nguồn cùng đi vào `RunControl`/cờ `control`: - **Cùng terminal**: phím `p`/`r`/`q` và Ctrl+C (`cli/keys.py`, `cli/interrupt.py`) → `RunControl` (an toàn giữa các luồng). Ctrl+C lần một = stop (xong batch hiện tại, commit, thoát mã 130, run `stopped`); lần hai thoát ngay, run còn `running` với `pending` dở dang, lần chạy sau (`--force-takeover` nếu chưa quá 2 phút) reconcile. - **Terminal khác**: `tgmirror pause|stop|run` ghi `runs.control='pause'|'stop'|'none'` (chỉ khi run đang `running`/`paused`; không có run đang chạy thì báo "không có clone nào đang chạy", mã 1, không ghi gì). `tgmirror run` mà cặp đang `paused` ở terminal khác thì chỉ xóa cờ (cho chạy tiếp ở đó), không mở run thứ hai. - Runner poll giữa các batch (rẻ, chỉ một `SELECT`) và mỗi `poll_interval` (2 giây) trong lúc ngủ (giãn cách của limiter và chờ FloodWait; ngủ ném `Interrupted` khi có **stop**), nên dừng được trong lúc chờ. `stop` → run `stopped`, `control` về `none`. - **`pause` giữ tại chỗ** (`Runner._hold`): xong batch hiện tại, run chuyển `paused` (tiến trình sống, heartbeat vẫn ghi mỗi 30 giây, không gửi gì) và poll mỗi `poll_interval` cho tới khi hết cờ pause (resume) hoặc có stop. Pause không cắt ngang lúc ngủ/chờ flood; nó có hiệu lực ở ranh giới batch kế tiếp. Sở hữu: - Một cặp chỉ có một run sống: `start_run` (`BEGIN IMMEDIATE`) từ chối (`RunBusy`) khi run `running`/`paused` của mirror có heartbeat còn mới (dưới 2 phút) trừ khi `--force-takeover` (khi đó run cũ ghi `failed('taken_over')`). Run có heartbeat cũ hơn 2 phút được coi là đã chết: ghi `failed('interrupted')` (kết thúc lúc nó còn tín hiệu cuối) rồi mở run mới. - Runner ghi heartbeat `updated_at` mỗi 30 giây (task nền) và sau mỗi lần commit. - Từ chối chạy: `waiting_flood` trước `resume_at` của một FloodWait (không phải `fail_reason='daily_cap'`: dòng do ngân sách học được đặt chỉ ghi chú giờ cửa sổ nhả, không chặn; trạng thái limiter đã lưu mới là thẩm quyền và tự dừng bằng `BudgetReached` ở lần ghi đầu, nên dòng cũ của `daily_cap` cố định trước phase 19d2 không khóa run mãi); `failed(peer_flood)` trong 24 giờ kể từ khi kết thúc (`engine/runs.py::check_runnable`, đọc run gần nhất của cặp; kiểm trước khi kết nối Telegram). Run mới không mang `fail_reason`/`resume_at` của run cũ. - Trong một process, runner và task heartbeat dùng chung một connection SQLite; `Store` khóa mọi phương thức bằng một `asyncio.Lock` để task này không chạy lệnh giữa transaction của task kia. - Một session Telethon chỉ nên được dùng bởi một process cùng lúc (SQLite session sẽ khóa), do đó một account chạy một clone tại một thời điểm (`Store.active_run` cho `pause`/`stop`/`run` tìm ra nó). ## Backup (Phase 11a) `tgmirror backup` (`store/backups.py`, `engine/backup.py`, `engine/backupdir.py`) không có đích nên không có `mirrors`/`msg_map`: bảng `backups` chỉ là nhật ký (`history` — **chưa nối vào lệnh `history` hiện có**, xem `06-lo-trinh.md` phần "chưa làm"), heartbeat/`control` để `pause`/`stop` từ terminal khác chạm tới, và nơi `flood_log.backup_id` trỏ vào (tách khỏi `run_id`: hai bảng `runs`/`backups` tự đánh số độc lập nên nếu dùng chung cột sẽ nhầm sự kiện flood của lần chạy này sang lần backup khác trùng id). Tiến độ **thật** không nằm ở `backups.cursor_to`/`stats_json` mà nằm ở chính thư mục backup: một tin được coi là đã backup xong khi (các) file media của nó đã ghi xong **và** dòng `messages.jsonl` của nó đã được append theo sau — append là thao tác lặp lại vô hại, nên không cần write-ahead. Một crash chỉ có thể để lại đúng dòng JSONL cuối cùng dở dang; `backupdir.iter_records`/`last_id` dừng lại ở đó (bỏ dòng cuối nếu không parse được), và lần backup sau chỉ cần tiếp tục từ `last_id` — không đọc `backups.cursor_to`. Cột đó (và `stats_json`) chỉ được `Store.advance_backup` cập nhật để hiển thị. Filter chỉ được đặt ở lần backup **đầu tiên** của một thư mục (`engine.backup.FiltersChanged` nếu lần sau đưa filter khác): khác mirror, backup không giữ gì tương đương `msg_map` để biết filter cũ đã loại những tin nào, nên không thể tiếp tục an toàn với filter mới — phải dùng thư mục khác. Quyết định D3 áp dụng y như chiến lược B (`engine.backup.check_source_for_backup`): backup luôn tải xuống (không có "copy phía server" cho một thư mục) nên nguồn `noforwards` luôn cần lời tuyên bố, ghi vào `backup.json` (`BackupManifest.protected_ack`) chứ không vào `backups` — thư mục backup tự mô tả, đọc được không cần tgmirror hay DB. ## Điều khiển của backup `tgmirror pause`/`stop` thử `store.active_run()` trước, rồi `store.active_backup()`: cùng cơ chế heartbeat/`control` như run (`Store.set_backup_control`, `read_backup_control`, `set_backup_status`, `finish_backup`, `heartbeat_backup`), cùng `RunControl` phía tiến trình (phím `p`/`r`/`q`, Ctrl+C dùng lại nguyên `engine/runner.py::RunControl`, không có lớp riêng cho backup). `start_backup` từ chối (`BackupBusy`) một thư mục đang có backup sống (heartbeat mới), như `RunBusy`; `--force-takeover` ghi đè. `begin_backup` cũng từ chối chạy trước khi nghỉ hết xong (`engine.runs.check_runnable`, dùng lại nguyên hàm của `run`/`clone`: `Backup` có đúng các trường `status`/`resume_at`/`fail_reason`/`ended_at`/`updated_at` mà hàm đó đọc, nên không cần bản riêng cho backup) khi lần backup gần nhất của thư mục đó là `waiting_flood` trước `resume_at`, hoặc `failed('peer_flood')` trong 24 giờ — như `RunWaiting`, mã thoát 3. Nhánh `daily_cap` của hàm đó không bao giờ xảy ra cho backup (backup không ghi Telegram nên không có cap ngày). Wizard (`cli/commands/backup.py::BackupFlow._check_existing`) gọi lại chính kiểm tra này **sớm hơn**, trước câu hỏi filter — như `CloneFlow._read_history` — để không bắt người dùng trả lời hết rồi mới bị từ chối; `begin_backup` vẫn là nơi kiểm tra thật sự (bảo vệ cả đường chỉ dùng cờ). ## Chưa làm ở Phase 11a Không có phân tích/ETA (`Runner._analyze`-tương đương), không có dòng tiến độ truyền file, không tải ảnh bìa video, không ghi `reply_to`, chưa nối vào `tgmirror history`, chưa có mục trong giao diện full-screen (menu). Wizard cổ điển (`tgmirror backup` không cờ) đã có, xem `02-cli-ux.md`. Xem `06-lo-trinh.md`, "Phase 11 — ghi chú" để biết đầy đủ. ## Thao tác tại chỗ (Phase 20, D10) `tgmirror delete` (`store/ops.py`, `engine/ops.py`) làm việc trên **chính** một kênh nên không có `mirrors`/`msg_map`. Migration 8 thêm hai bảng và một cột: ```sql ops(id, account, kind, chat_id, chat_title, chat_kind, filters_json, options_json, status, control, resume_at, fail_reason, stats_json, created_at, ended_at, updated_at) op_items(op_id, msg_id, unit_id, grouped_id, status, reason, before_json, new_msg_id, PRIMARY KEY (op_id, msg_id)) -- unit_id = id tin đầu của đơn vị (album chung một unit_id) flood_log.op_id ``` - `ops.status`: `planned` (danh sách đã đóng băng, chờ xác nhận) → `running`/`paused` → `done`/`stopped`/`waiting_flood`/`failed`; `cancelled` là plan bị bỏ. `stats_json`: `planned` (số tin trong plan, đặt lúc tạo), `done`, `skipped` (đã đổi, không còn khớp filter), `gone` (đã mất khi tới lượt), `failed`. Heartbeat/`control` như `runs`/`backups`; `start_op` từ chối (`OpBusy`) khi một thao tác khác trên **cùng kênh** còn sống, `--force-takeover` ghi đè. - `op_items.status`: `planned` → `pending` → `done`, hoặc `skipped` (+ `reason` `changed`/`gone`) hoặc `failed`. Khác backup, **tiến độ thật nằm trong SQLite** (luật 3): `pending` được ghi trong một transaction **trước** lời gọi xoá, `done` trong một transaction sau nó (`Store.mark_op_items` cộng luôn bộ đếm). `before_json` dùng từ Phase 20.3: với `edit`/`undo` là `{"before": , "after": }` của từng tin; `new_msg_id` (`repost`) có sẵn cột nhưng chưa dùng. - **Resume/reconcile** (`OpRunner._settle_pending`, chạy trước mọi batch): với các item `pending` của lần chạy trước, đọc kênh theo id — id vắng mặt = lời gọi đã xoá nó (`done`); id còn nguyên = chưa xoá (`planned`, batch kế tiếp đọc lại và xoá như mọi item khác). Một lỗi mà Telegram từ chối rõ ràng (FloodWait, mất quyền) trả luôn lô về `planned` ngay tại chỗ; chỉ `Transient`/kill để `pending` lại. - **`ops.kind` `repost`** (20.4): `options_json` có `delete_original` và `silent`; item thêm trạng thái **`reposted`** (bản mới đã có và `new_msg_id` đã lưu, bản gốc chưa xoá — đây chính là write-ahead cho việc xoá, nên một lần chạy lại xoá nốt mà không đăng thêm); `before_json` của item ghi `{"topic", "tail"}` (topic của tin; id tin cuối của kênh ngay trước khi gửi đơn vị đó, ghi cùng lúc với `pending`). Reconcile `pending` bằng `engine/reconcile.judge` trên đuôi kênh từ `tail`. `stats.same_file` đếm tin mới vẫn mang file id cũ. - **`ops.kind`** có `delete`, `edit` (20.3) và `undo` (20.3, `options_json.undo_of` = số của lần sửa nó trả lại; `options_json.transform` của `edit` = transform đã lập plan). Với `edit`/`undo`, `pending` được ghi trước **từng** lần sửa (một lời gọi mỗi tin) và reconcile đọc văn bản hiện tại: bằng `after` → `done`, bằng `before` → `planned`, khác → `skipped` (`changed`). Một lô `edit` là 10 tin (không phải 100 như `delete`). - **`ops.options_json`** (Phase 20.2): `backup_dir` (thư mục lưới an toàn của plan, đặt khi backup **bắt đầu**) và `backup_done` (đúng khi backup đã xong). Backup chạy sau xác nhận và trước `start_op`; `delete --resume` của một plan còn `planned` đọc hai khóa này để làm tiếp đúng thư mục đó hoặc bỏ qua backup đã xong. Backup đó là một dòng `backups` bình thường (`B`), không có khóa ngoại tới `ops`. - `tgmirror pause|stop` thử `active_run`, `active_backup`, rồi `active_op`. `appdata export` từ chối khi có thao tác sống. ## Restore (Phase 11b) Ngược với backup, `tgmirror restore` **là** một `Run` bình thường — dùng lại nguyên `mirrors`/`msg_map`/write-ahead/reconcile ở trên, không phải một cơ chế mới. Chỉ khác hai chỗ: - **`options_json.from_backup`** (ghi ở `runs`, như `retry_of`, không đưa vào `mirrors.options_json` qua `RunOptions.for_pair`): đường dẫn thư mục backup lần chạy này đọc thay vì gateway. Thuộc về lần chạy chứ không phải cặp, vì sau khi restore xong cặp đó có thể quay lại là một clone sống bình thường (`clone`/`run` không có `from_backup`) mà không cần dọn gì. `tgmirror run`/`tgmirror retry` tiếp tục một restore bị dừng đọc lại giá trị này từ dòng `runs` trước đó (`cli/commands/run.py::reader_override_for`), dựng lại `BackupReader` đúng thư mục. - **`mirrors.src_id` là id kênh gốc** (`BackupManifest.src_id`, kênh gốc có thể đã mất): vì khóa duy nhất của `mirrors` chỉ là `(src_id, dst_id)`, không có `mode`, một restore và một lần `clone`/`run` trực tiếp của **đúng kênh gốc đó** vào cùng đích chia sẻ một mirror/`msg_map`. Vì id tin Telegram giữ nguyên qua backup, việc này chống trùng tự nhiên: một tin đã "done" qua restore thì một clone trực tiếp sau đó bỏ qua nó (bước 3 của "Resume và delta" ở trên), và ngược lại. Không có bảng mới, không có migration: `RunOptions.from_backup` là một khóa mới trong `options_json` (cơ chế "khóa lạ bị bỏ qua" của `to_json`/`from_json` đã có sẵn chỗ cho việc này, như `02-cli-ux.md`/`06-lo-trinh.md` đã ghi cho các khóa khác). **Chia/gộp topic (Phase 20b, `ops.kind` `move`)** dùng nguyên các bảng trên: giống `repost` với `delete_original` luôn bật, nhưng mỗi item ghi `before_json {"dest": , "dest_id": }` (không tạo topic lúc lập plan; `OpRunner._topic_titled` tìm theo tên rồi mới tạo khi áp dụng) và ghi chú `pending` giữ thêm `dest`. `unit_id` của một lần gộp là `vị trí topic × 10¹² + id đầu` để `op_units` đi hết topic này rồi mới sang topic kế. `options_json.drop_topics` (cả `move` lẫn `delete` của `topics delete`) là các id topic sẽ bị xoá khi đã rỗng (`OpRunner._drop_topics`, sau khi mọi item xong; còn tin thì giữ topic): `stats.topics_dropped`/`topics_kept`. Reply giữa các tin cùng được chuyển đọc `op_items.new_msg_id` (`Store.op_new_ids`). **Đồng bộ edit/delete nguồn → đích (Phase 17, `tgmirror sync-changes`)** không thêm bảng hay migration: nó đọc `msg_map` (`Store.mirror_copy_rows`: nguồn, đích, `grouped_id`, bản sao hay tin giữ chỗ), đọc lại nguồn theo id rồi lập hai plan bằng máy của `ops`/`op_items` ở trên — một `edit` (item `before_json {"before","after"}`) và một `delete` (item `before_json {"src": }`) trên kênh **đích**. `options_json` của cả hai ghi `sync_src` (id kênh nguồn; `Op.sync_src`), `mirror`, `run`; với `sync_src`, `OpRunner._delete_batch` đọc lại nguồn trước mỗi lô và giữ bản sao nào có tin nguồn xuất hiện lại (`skipped`/`changed`). Chữ mong đợi của bản sao được tính lại, không lưu: `msg_map.ts` chỉ là lúc xử lý lô, nên không dùng để so với `edit_date`.