feat: implement new storage design per issue #2
- Storage: Change from per-user to per-group JSON files
- Data location: ~/.jigaido/ instead of apps/telegram-bot/data/
- Group bounties: data/{group_id}/group.json
- User tracking: data/{group_id}/{user_id}.json
- Personal bounties: data/{user_id}/user.json
- Update commands.py for new storage model
- Update bot.py to remove admin handlers
- Update tests to reflect created_by_user_id field
- Update SPEC.md with new design
Addresses user feedback from issue #2
This commit is contained in:
shokollm
89
SPEC.md
89
SPEC.md
@@ -13,15 +13,14 @@ JIGAIDO is a Telegram bot that lets groups and individuals track bounties — ta
|
||||
- **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.
|
||||
- **Informed by**: Every bounty stores the user ID of who posted/added it.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Stack
|
||||
- **Bot**: `python-telegram-bot` (pure Python, no C extensions)
|
||||
- **Storage**: Per-user JSON files (zero-setup, no DB server)
|
||||
- **Storage**: Per-group JSON files (zero-setup, no DB server)
|
||||
- **Date parsing**: `dateparser`
|
||||
- **Runtime**: Python 3.10+
|
||||
- **Deployment**: Any $5 VPS with Python 3.10+
|
||||
@@ -29,57 +28,71 @@ JIGAIDO is a Telegram bot that lets groups and individuals track bounties — ta
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
jigaido/
|
||||
├── apps/
|
||||
│ └── telegram-bot/ # Telegram bot app
|
||||
│ ├── bot.py # Entrypoint
|
||||
│ ├── commands.py # Command handlers
|
||||
│ ├── storage.py # JSON file storage
|
||||
│ ├── data/
|
||||
│ │ └── users/ # Per-user JSON files
|
||||
│ │ └── {telegram_user_id}.json
|
||||
│ ├── requirements.txt
|
||||
│ └── .env.example
|
||||
├── SPEC.md # This document
|
||||
├── README.md
|
||||
└── CONTRIBUTING.md
|
||||
~/.jigaido/ # Data root (~/.jigaido/)
|
||||
├── {group_id}/
|
||||
│ ├── group.json # Group bounties
|
||||
│ └── {user_id}.json # User tracking within this group
|
||||
└── {user_id}/
|
||||
└── user.json # User's personal bounties (DM mode)
|
||||
```
|
||||
|
||||
**Note:** Data directory is at `~/.jigaido/` (home directory), NOT inside the repository or app directory.
|
||||
|
||||
### Storage Design
|
||||
|
||||
**File structure (`data/users/{telegram_user_id}.json`):**
|
||||
**File: `data/{group_id}/group.json`**
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": 123,
|
||||
"username": "alice",
|
||||
"personal_bounties": [
|
||||
"bounties": [
|
||||
{
|
||||
"id": 1,
|
||||
"created_by_user_id": 123456,
|
||||
"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}
|
||||
"next_id": 2
|
||||
}
|
||||
```
|
||||
|
||||
**File: `data/{group_id}/{user_id}.json`**
|
||||
|
||||
```json
|
||||
{
|
||||
"tracked": [
|
||||
{"bounty_id": 1, "created_at": 1735600000}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**File: `data/{user_id}/user.json`**
|
||||
|
||||
```json
|
||||
{
|
||||
"bounties": [
|
||||
{
|
||||
"id": 1,
|
||||
"text": "Personal task",
|
||||
"link": null,
|
||||
"due_date_ts": 1735689600,
|
||||
"created_at": 1735603200
|
||||
}
|
||||
],
|
||||
"next_id": 2
|
||||
}
|
||||
```
|
||||
|
||||
**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.
|
||||
1. **Group-isolated storage** — Each group has its own directory. No cross-group access.
|
||||
2. **Bounty IDs are sequential per group.json** — Not global. Each group's file has its own ID counter.
|
||||
3. **Atomic writes** — Uses `tempfile` + `rename` for safe writes.
|
||||
4. **No reminders in v1** — Dropped for simplicity.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
### In Group
|
||||
@@ -87,23 +100,23 @@ jigaido/
|
||||
| Command | Who | Description |
|
||||
|---|---|---|
|
||||
| `/bounty` | anyone | List all bounties in this group |
|
||||
| `/my` | anyone | List bounties tracked by you |
|
||||
| `/my` | anyone | List bounties tracked by you in this group |
|
||||
| `/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 |
|
||||
| `/track <bounty_id>` | anyone | Track a group bounty |
|
||||
| `/untrack <bounty_id>` | anyone | Stop tracking a bounty |
|
||||
|
||||
### In DM (1:1 with bot)
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `/bounty` | List all your personal bounties |
|
||||
| `/my` | List bounties you're tracking |
|
||||
| `/my` | List all your personal bounties |
|
||||
| `/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 |
|
||||
| `/track <bounty_id>` | Add a personal bounty to your tracking |
|
||||
| `/track <bounty_id>` | Track a personal bounty |
|
||||
|
||||
### Add/Update Syntax
|
||||
|
||||
@@ -118,12 +131,6 @@ jigaido/
|
||||
|
||||
---
|
||||
|
||||
## Informed By
|
||||
|
||||
When a user triggers `/add`, the bot captures `message.from_user.username` and stores it in `informed_by_username`. This is displayed on bounty listings so the group/DM knows who posted or requested the bounty.
|
||||
|
||||
---
|
||||
|
||||
## Due Date Parsing
|
||||
|
||||
Uses `dateparser` library. Examples:
|
||||
@@ -142,7 +149,7 @@ Stored as Unix timestamp. User-facing display can be localized/converted to any
|
||||
## Error Handling
|
||||
|
||||
- Unknown command → help text with available commands
|
||||
- `/update`/`/delete` by non-creator → "⛔ Group creator only."
|
||||
- `/update`/`/delete` by non-creator → "⛔ Only the creator can edit/delete this bounty."
|
||||
- `/track` already tracked → "Already tracking" (idempotent)
|
||||
- `/untrack` not tracked → "Not tracking" (idempotent)
|
||||
- Bounty not found → "Bounty not found"
|
||||
|
||||
Reference in New Issue
Block a user