shoko/jigaido
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Replace SQLite with per-user JSON storage (fixes #2)

Browse Source 
- Add storage.py with load_user(), save_user(), next_bounty_id()
- Rewrite commands.py to use JSON storage (simplified)
- Remove db.py, schema.sql, cron.py, test_db.py
- Update SPEC.md to reflect new architecture
- Admin model removed (anyone can add, creator only can edit/delete)
- No reminders in v1
This commit is contained in:
shokollm
2026-04-01 10:02:51 +00:00
parent 8647f2f4b8
commit 8bb964fdd0
8 changed files with 286 additions and 1058 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
SPEC.md
View File

@@ -6,15 +6,14 @@
## Overview
JIGAIDO is a Telegram bot that lets groups and individuals track bounties — tasks, obligations, and deadlines — with optional due dates and personal tracking/reminders.
JIGAIDO is a Telegram bot that lets groups and individuals track bounties — tasks, obligations, and deadlines — with optional due dates and personal tracking.
- **Group mode**: Each Telegram group has its own bounty list. Only group admins can add/update/delete bounties. Any member can track/untrack.
- **DM mode**: Personal bounty list. No admin restrictions — anyone can manage their own bounties.
- **Tracking**: Users can add any bounty (group or DM) to their personal tracking list.
- **Reminders**: Daily cron checks for due dates within 7 days and DMs the user.
- **Due dates**: Free-form text (`"april 15"`, `"in 3 days"`, `"tomorrow"`) parsed at add time, stored as Unix timestamp. If unparseable, stored as `NULL` — no reminder.
- **Links**: Optional. If provided, deduplicated per group (no two bounties in the same group can share the same link). Multiple links in one bounty: first link only, user can update later.
- **Informed by**: Every bounty stores the Telegram username of who posted/added it (not who created the record — the person whose message triggered the add).
- **Group mode**: Each Telegram group has its own bounty list. Anyone can add bounties. Only creator can edit/delete.
- **DM mode**: Personal bounty list. Anyone can manage their own bounties.
- **Tracking**: Users can track any bounty (group or personal) to their tracking list.
- **Due dates**: Free-form text (`"april 15"`, `"in 3 days"`, `"tomorrow"`) parsed at add time, stored as Unix timestamp. If unparseable, stored as `NULL`.
- **Links**: Optional. If provided, stored with the bounty.
- **Informed by**: Every bounty stores the Telegram username of who posted/added it.
---
@@ -22,7 +21,7 @@ JIGAIDO is a Telegram bot that lets groups and individuals track bounties — ta
### Stack
- **Bot**: `python-telegram-bot` (pure Python, no C extensions)
- **Database**: SQLite (zero-install, single file)
- **Storage**: Per-user JSON files (zero-setup, no DB server)
- **Date parsing**: `dateparser`
- **Runtime**: Python 3.10+
- **Deployment**: Any $5 VPS with Python 3.10+
@@ -35,9 +34,10 @@ jigaido/
│ └── telegram-bot/ # Telegram bot app
│ ├── bot.py # Entrypoint
│ ├── commands.py # Command handlers
│ ├── cron.py # Daily reminder job
│ ├── db.py # SQLite wrapper
│ ├── schema.sql # Database schema
│ ├── storage.py # JSON file storage
│ ├── data/
│ │ └── users/ # Per-user JSON files
│ │ └── {telegram_user_id}.json
│ ├── requirements.txt
│ └── .env.example
├── SPEC.md # This document
@@ -45,64 +45,38 @@ jigaido/
└── CONTRIBUTING.md
```
---
### Storage Design
## Database Schema
**File structure (`data/users/{telegram_user_id}.json`):**
```sql
CREATE TABLE groups (
id INTEGER PRIMARY KEY AUTOINCREMENT,
telegram_chat_id INTEGER UNIQUE NOT NULL,
creator_user_id INTEGER NOT NULL,
created_at INTEGER NOT NULL DEFAULT (unixepoch())
);
CREATE TABLE group_admins (
group_id INTEGER REFERENCES groups(id) ON DELETE CASCADE,
user_id INTEGER NOT NULL,
PRIMARY KEY (group_id, user_id)
);
CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
telegram_user_id INTEGER UNIQUE NOT NULL,
username TEXT,
created_at INTEGER NOT NULL DEFAULT (unixepoch())
);
CREATE TABLE bounties (
id INTEGER PRIMARY KEY AUTOINCREMENT,
group_id INTEGER REFERENCES groups(id) ON DELETE CASCADE,
created_by_user_id INTEGER REFERENCES users(id),
informed_by_username TEXT NOT NULL,
text TEXT,
link TEXT,
due_date_ts INTEGER,
created_at INTEGER NOT NULL DEFAULT (unixepoch()),
UNIQUE(group_id, link)
);
CREATE TABLE user_bounty_tracking (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
bounty_id INTEGER NOT NULL REFERENCES bounties(id) ON DELETE CASCADE,
added_at INTEGER NOT NULL DEFAULT (unixepoch()),
UNIQUE(user_id, bounty_id)
);
CREATE TABLE reminder_log (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
bounty_id INTEGER NOT NULL REFERENCES bounties(id) ON DELETE CASCADE,
reminded_at INTEGER NOT NULL DEFAULT (unixepoch()),
UNIQUE(user_id, bounty_id)
);
```json
{
"user_id": 123,
"username": "alice",
"personal_bounties": [
{
"id": 1,
"text": "Fix login bug",
"link": "https://github.com/example/repo/issues/1",
"due_date_ts": 1735689600,
"group_id": null,
"informed_by_username": "alice",
"created_at": 1735603200
}
],
"tracked_bounties": [
{"bounty_id": 5, "group_id": -1001, "created_at": 1735600000},
{"bounty_id": 3, "group_id": null, "created_at": 1735590000}
]
}
```
### Notes
- `group_id = NULL` means a personal/DM bounty.
- `UNIQUE(group_id, link)` — only enforced when `link IS NOT NULL` (SQLite treats NULL as distinct).
- `reminder_log` dedup ensures a user only gets one reminder per bounty.
**Key design decisions:**
1. **Single file per user** — Personal bounties live in the creator's file. Group bounties also live in creator's file with `group_id` set.
2. **Bounty IDs are sequential integers per file** — Not global. Each user's file has its own ID counter.
3. **Atomic writes** — Uses `tempfile` + `rename` for safe writes.
4. **No reminders in v1** — Dropped for simplicity.
---
@@ -113,24 +87,22 @@ CREATE TABLE reminder_log (
| Command | Who | Description |
|---|---|---|
| `/bounty` | anyone | List all bounties in this group |
| `/my` | anyone | List bounties tracked by you in this group |
| `/add <text> [link] [due date]` | admin only | Add a new bounty to the group |
| `/update <bounty_id> [text] [link] [due_date]` | admin only | Update an existing bounty |
| `/delete <bounty_id>` | admin only | Delete a bounty |
| `/my` | anyone | List bounties tracked by you |
| `/add <text> [link] [due date]` | anyone | Add a new bounty to the group |
| `/update <bounty_id> [text] [link] [due_date]` | creator only | Update an existing bounty |
| `/delete <bounty_id>` | creator only | Delete a bounty |
| `/track <bounty_id>` | anyone | Add a group bounty to your tracking |
| `/untrack <bounty_id>` | anyone | Remove a bounty from your tracking |
| `/admin_add <user>` | creator only | Promote a user to admin |
| `/admin_remove <user>` | creator only | Demote an admin |
### In DM (1:1 with bot)
| Command | Description |
|---|---|
| `/bounty` | List all your personal bounties |
| `/my` | List all your tracked personal bounties |
| `/my` | List bounties you're tracking |
| `/add <text> [link] [due date]` | Add a personal bounty |
| `/update <bounty_id> [text] [link] [due_date]` | Update a personal bounty |
| `/delete <bounty_id>` | Delete a personal bounty (owner only) |
| `/delete <bounty_id>` | Delete a personal bounty |
| `/track <bounty_id>` | Add a personal bounty to your tracking |
### Add/Update Syntax
@@ -143,13 +115,6 @@ CREATE TABLE reminder_log (
- `link` is optional
- `due_date` is optional, free-form
- If link already exists in group → rejected with error
### Tracking
- `/track <bounty_id>` — works in both group and DM. In group: tracks a group bounty. In DM: tracks a personal bounty.
- Users can track any bounty regardless of who created it.
- A bounty can be tracked by multiple users.
---
@@ -168,40 +133,26 @@ Uses `dateparser` library. Examples:
- `"2026-04-15"`
- `"next friday"`
If parsing fails → `due_date_ts = NULL`. No error is shown to user, reminder just won't fire.
If parsing fails → `due_date_ts = NULL`. No error is shown to user.
Stored as Unix timestamp. User-facing display can be localized/converted to any timezone at render time.
---
## Reminders (Cron)
Runs daily (e.g., 09:00 local). For each user:
1. Find tracked bounties where `due_date_ts - now() < 7 days`
2. Exclude any already in `reminder_log` for that user
3. Send DM: `"Bounty '{title}' is due in {N} days."`
4. Insert into `reminder_log`
Does not re-remind. If a bounty is 2 days away today, you get one message. Tomorrow you don't get another.
---
## Admin Management
- **Creator**: The user who first added the bot to the group. Stored as `creator_user_id` in `groups`. Only the creator can run `/admin_add` and `/admin_remove`.
- **Admins**: Added via `/admin_add <username>`. Can add/update/delete any bounty in the group. Regular members can only track/untrack.
- First admin assignment is automatic when the bot detects a new group.
---
## Error Handling
- Unknown command → help text with available commands
- `/add` with duplicate link in same group → rejection message
- `/update`/`/delete` by non-admin → "Admin only" message
- `/admin_add`/`/admin_remove` by non-creator → "Creator only" message
- `/track` already tracked → "Already tracking" (idempotent, no error)
- `/untrack` not tracked → "Not tracking" (idempotent, no error)
- `/update`/`/delete` by non-creator → "⛔ Group creator only."
- `/track` already tracked → "Already tracking" (idempotent)
- `/untrack` not tracked → "Not tracking" (idempotent)
- Bounty not found → "Bounty not found"
- User not found → "User not found"
---
## When to Revert to SQLite
- Multiple concurrent users with write conflicts
- Complex queries across users
- Reminder system with proper dedup
- Scale > 1,000 users
- Need ACID guarantees on concurrent writes