# Copykar Improvements Implementation Plan

> **For agentic workers:** Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Publish through the bot account, make history fetching controllable, allow
automatic source→target routing, rebuild the dashboard from the real metric inventory,
and track error resolution — with a Telegram note to admins after every task.

**Architecture:** Same service layout (`collector` → `admin_bot` review → Redis per-target
queues → `publisher`). Changes are additive: a new `targets.auto_source_ids` column drives
auto-routing, `error_logs` gains resolution columns, and the admin bot's channel lists
become button menus instead of one card per channel.

**Tech Stack:** Python 3.12, Telethon 1.44, asyncpg/PostgreSQL 16, Redis 7,
prometheus-client, Grafana 11.2, Docker Compose.

**Spec:** User request of 2026-08-28 (8 items), recorded in the task list below.

## Global Constraints

- All admin-facing bot text is Persian; keep the existing emoji/HTML card style.
- Telegram limits: media caption ≤ 1024 chars, text message ≤ 4096 chars, callback data ≤ 64 bytes.
- No AI/model attribution in code comments or commit messages (user's GEMINI.md).
- Minimal diffs — no drive-by refactors of untouched code.
- Never commit `.env`. Do not commit at all without asking.
- Every task ends with: tests pass, app rebuilt+restarted, Telegram note sent to admins.

---

### Task 1: Publish through the bot account, not the userbot

**Files:** Modify `main.py`, `services/publisher.py`; Test `tests/test_publisher_failures.py`

**Interfaces:** Produces — `PublisherService(..., client=<bot client>)`.

- [ ] Pass `admin_bot.client` as the publisher client in `main.py`.
- [ ] Publisher must not `client.start()` a client the admin bot already started.
- [ ] Keep the permanent/transient failure split; a bot lacking rights raises
      `ChatAdminRequiredError`, already classified permanent.
- [ ] Update the broken-target message to say the **bot** needs admin rights.
- [ ] Run suite, rebuild, restart, notify admins.

### Task 2: Controllable history fetch

**Files:** Modify `services/collector.py`, `services/admin_bot.py`; Test `tests/test_scrape_history.py`

**Interfaces:** Produces — `scrape_channel_history(...) -> ScrapeResult` with fields
`collected`, `already_stored`, `duplicates`, `scanned`.

- [ ] Return a structured result instead of a bare int so the admin sees *why* nothing was added.
- [ ] Report all four counters in the Persian progress message.
- [ ] Add a `🔢 تعداد دلخواه` button per source → state `wait_fetch_count` → user sends a number (1–500).
- [ ] Keep the 20/50 quick buttons.
- [ ] Run suite, rebuild, restart, notify admins.

### Task 3: Automatic source→target routing

**Files:** Modify `db/database.py`, `db/repository.py`, `db/models.py`, `services/admin_bot.py`; Test `tests/test_auto_routing.py`

**Interfaces:** Produces — `targets.auto_source_ids BIGINT[]`,
`Repository.set_target_auto_sources(target_id, source_channel_ids)`,
`Repository.get_targets_auto_routed_from(source_channel_id)`.

- [ ] Add `auto_source_ids BIGINT[] DEFAULT '{}'` column + migration.
- [ ] Target config card gains `🤖 ارسال خودکار از مبدا` button showing every source as a toggle.
- [ ] After the review card is sent, auto-route: rewrite for each subscribed target and enqueue.
- [ ] The admin review card is still posted — auto-routing never replaces it.
- [ ] Run suite, rebuild, restart, notify admins.

### Task 4: Channel lists as button menus

**Files:** Modify `services/admin_bot.py`

- [ ] `/sources` and `/targets` send ONE message with one button per channel.
- [ ] `src_view:{id}` / `trg_view:{id}` open that channel's card with its options.
- [ ] Every card gets a back button to its list.
- [ ] Run suite, rebuild, restart, notify admins.

### Task 5: Error resolution tracking + caption fix

**Files:** Modify `db/database.py`, `db/repository.py`, `core/metrics.py`, `core/error_logger.py`, `services/admin_bot.py`; Test `tests/test_error_tracking.py`

**Interfaces:** Produces — `error_logs.resolved/resolved_at/resolved_note`,
`Repository.get_open_error_summary()`, `Repository.resolve_errors(error_type, service_name, note)`,
gauges `copykar_errors_open`, counter `copykar_errors_resolved_total`.

- [ ] Add resolution columns + migration.
- [ ] Fix `MediaCaptionTooLongError`: clamp preview/review captions to Telegram limits.
- [ ] `/errors` command lists open error groups with a `✅ رفع شد` button per group.
- [ ] Publish `copykar_errors_open` and `copykar_errors_resolved_total`; refresh the gauge periodically.
- [ ] Mark the already-fixed historical errors resolved.
- [ ] Run suite, rebuild, restart, notify admins.

### Task 6: Rebuild the Grafana dashboard

**Files:** Rewrite `monitoring/grafana/dashboards/copykar.json`

- [ ] Rebuild from the live metric inventory; every metric appears exactly once.
- [ ] Remove the duplicated queue reading (`copykar_redis_queue_size` total vs per-target gauge).
- [ ] Max 3 panels per row, Persian titles + descriptions.
- [ ] Include the new error-health panels.
- [ ] Restart Grafana, verify panels return data, notify admins.