103 lines
5.1 KiB
Markdown
103 lines
5.1 KiB
Markdown
# 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.
|