student contributions + QR

app/bot/handlers/__init__.py

@@ -1,6 +1,6 @@
 from aiogram import Router
 
-from app.bot.handlers import admin, gate, groups, inline, library, menu, search, start
+from app.bot.handlers import admin, admin_queue, contribute, gate, groups, inline, library, menu, search, start
 
 
 def build_router() -> Router:
@@ -8,10 +8,12 @@ def build_router() -> Router:
     # order matters: specific handlers first, plain-text search fallback LAST
     router.include_router(gate.router)
     router.include_router(admin.router)
+    router.include_router(admin_queue.router)
     router.include_router(groups.router)
     router.include_router(start.router)
     router.include_router(menu.router)
     router.include_router(library.router)
+    router.include_router(contribute.router)
     router.include_router(inline.router)
     router.include_router(search.router)
     return router

app/bot/handlers/admin.py

@@ -18,6 +18,7 @@ from app.core.seed_courses import FRESHMAN_COURSES
 from app.db.models import User
 from app.db.repos import library as repo
 from app.db.repos import stats as stats_repo
+from app.db.repos import submissions as sub_repo
 from app.core import season as clock
 from app.db.repos import users as users_repo
 from app.services import growth
@@ -48,6 +49,7 @@ HELP = (
     "/seedcourses : add the Year-1 course list (safe to run twice)\n"
     "/courses : list courses with ids\n"
     "/delcourse <id> [move_files_to_id] : delete a course (refuses if it still has files)\n"
+    "/queue : review files students sent (one card at a time: Accept / Course / Reject)\n"
     "/growth : where new students come from + a funnel per source\n"
     "/poster [tag] : printable A4 poster with a QR code (tag = where you will put it, e.g. dorm5)\n"
     "/emptycourses : list courses with no files, with a button to delete them all\n"
@@ -235,6 +237,17 @@ async def poster(message: Message, command: CommandObject) -> None:
         caption=f"🖨 Print it. The QR opens {link}\nSource tag: <b>{tag}</b>. See who came from it in /growth. "
         "One poster per place works best: /poster dorm5, /poster cafeteria …",
     )
+    # the same QR as images, to drop into your own Amharic design (Canva, Word, Photoshop...)
+    from app.services.qr import qr_png
+
+    await message.answer_document(
+        BufferedInputFile(qr_png(link), filename=f"qr-{tag}.png"),
+        caption="🔳 QR on white (safest to print). Keep a clear white margin around it and do not shrink it below ~3 cm.",
+    )
+    await message.answer_document(
+        BufferedInputFile(qr_png(link, transparent=True), filename=f"qr-{tag}-transparent.png"),
+        caption="🔳 QR with a transparent background: place it on a LIGHT area of your design.",
+    )
 
 
 @router.message(Command("emptycourses"))
@@ -324,6 +337,7 @@ async def stats(message: Message, session: AsyncSession) -> None:
         f"Users: <b>{s['users']}</b> (passed gate {s['gate_passed']}, onboarded {s['onboarded']})\n"
         f"Active today: <b>{s['active_today']}</b>\n"
         f"Referrals: <b>{s['referrals']}</b>\n"
+        f"Student files waiting: <b>{await sub_repo.pending_total(session)}</b>\n"
         f"Courses: <b>{s['courses']}</b> · Files: <b>{s['materials']}</b> · Downloads: <b>{s['downloads']}</b>"
     )
 

app/bot/handlers/admin_queue.py

@@ -0,0 +1,232 @@
+"""Admin review of student files: one card at a time, three taps, no per-file spam."""
+import html
+from typing import Optional
+
+from aiogram import F, Router
+from aiogram.filters import Command
+from aiogram.types import CallbackQuery, InlineKeyboardButton, InlineKeyboardMarkup, Message
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.bot.handlers.admin import IsAdmin
+from app.db.models import Submission
+from app.db.repos import library as lib_repo
+from app.db.repos import submissions as sub_repo
+from app.db.repos import users as users_repo
+from app.services import classifier as C
+from app.services import contrib_rules as K
+from app.services import contributions as contrib
+from app.services import library as lib
+
+router = Router()
+router.message.filter(IsAdmin())
+router.callback_query.filter(IsAdmin())
+_skipped: dict[int, set[int]] = {}  # admin_id -> submissions skipped in this review round
+PAGE = 8
+REASON_LABEL = {"duplicate": "♻️ Duplicate", "quality": "📉 Low quality", "notallowed": "🚫 Not allowed"}
+
+
+def _b(text: str, data: str) -> InlineKeyboardButton:
+    return InlineKeyboardButton(text=text, callback_data=data)
+
+
+def _course_label(c) -> str:
+    return f"{c.code + ' ' if c.code else ''}{c.name}" if c else "❓ no course yet"
+
+
+def _mb(size: Optional[int]) -> str:
+    return f"{size / 1048576:.1f} MB" if size else "?"
+
+
+async def _card(session: AsyncSession, sub: Submission) -> Optional[tuple[str, InlineKeyboardMarkup]]:
+    material = await lib_repo.get_material(session, sub.material_id) if sub.material_id else None
+    if material is None:
+        return None
+    user = await users_repo.get(session, sub.user_id)
+    course = await lib_repo.get_course(session, material.course_id) if material.course_id else None
+    approved = await sub_repo.approved_count(session, sub.user_id)
+    left = await sub_repo.pending_total(session)
+    who = html.escape((user.full_name if user else "?") or "?")
+    handle = f" @{html.escape(user.username)}" if user and user.username else ""
+    text = (
+        f"📥 <b>Submission #{sub.id}</b> · {left} waiting\n"
+        f"👤 {who}{handle} · id{sub.user_id} · {approved} approved before\n"
+        f"📎 <i>{html.escape((sub.file_name or material.source_name or '?')[:70])}</i> · {_mb(material.size)}"
+        f"{f' · {material.pages} p' if material.pages else ''}\n"
+        f"📘 {html.escape(_course_label(course))} · <b>{material.kind}</b>\n“{html.escape(material.title)}”"
+    )
+    if sub.note:
+        text += f"\n⚠️ {html.escape(sub.note)}"
+    rows = [
+        [_b("✅ Accept", f"qq:a:{sub.id}")],
+        [_b("✏️ Course", f"qq:c:{sub.id}"), _b("🗑 Reject", f"qq:r:{sub.id}")],
+    ]
+    if sub.dup_of:
+        rows.append([_b(f"♻️ Replace #{sub.dup_of} with this", f"qq:p:{sub.id}")])
+    rows.append([_b("⏭ Skip", f"qq:k:{sub.id}")])
+    return text, InlineKeyboardMarkup(inline_keyboard=rows)
+
+
+async def show_next(bot, session: AsyncSession, admin_id: int, chat_id: int) -> None:
+    """Send the next waiting card (or say the queue is empty)."""
+    skip = _skipped.setdefault(admin_id, set())
+    for _ in range(25):  # cards whose file vanished are cleaned up on the way
+        sub = await sub_repo.next_pending(session, skip)
+        if sub is None:
+            _skipped.pop(admin_id, None)
+            await bot.send_message(chat_id, "🎉 Nothing is waiting for review.")
+            return
+        card = await _card(session, sub)
+        if card:
+            await bot.send_message(chat_id, card[0], reply_markup=card[1])
+            return
+        await contrib.reject(bot, session, sub, "quality")  # file gone: close it silently
+
+
+async def _finish(call: CallbackQuery, session: AsyncSession, text: str) -> None:
+    """Replace the card with the result, then bring the next one."""
+    if call.message:
+        try:
+            await call.message.edit_text(text)
+        except Exception:
+            pass
+    await show_next(call.bot, session, call.from_user.id, call.message.chat.id)
+
+
+async def _pending(call: CallbackQuery, session: AsyncSession, sid: int) -> Optional[Submission]:
+    sub = await sub_repo.get(session, sid)
+    if sub is None or sub.status != "pending":
+        await call.answer("Already handled.", show_alert=True)
+        return None
+    return sub
+
+
+async def _rerender(call: CallbackQuery, session: AsyncSession, sub: Submission) -> None:
+    card = await _card(session, sub)
+    if card and call.message:
+        try:
+            await call.message.edit_text(card[0], reply_markup=card[1])
+        except Exception:
+            pass
+
+
+@router.message(Command("queue"))
+async def queue(message: Message, session: AsyncSession) -> None:
+    _skipped.pop(message.from_user.id, None)
+    await show_next(message.bot, session, message.from_user.id, message.chat.id)
+
+
+@router.callback_query(F.data == "qq:start")
+async def start(call: CallbackQuery, session: AsyncSession) -> None:
+    await call.answer()
+    _skipped.pop(call.from_user.id, None)
+    await show_next(call.bot, session, call.from_user.id, call.message.chat.id)
+
+
+@router.callback_query(F.data.startswith("qq:a:"))
+async def accept(call: CallbackQuery, session: AsyncSession) -> None:
+    sub = await _pending(call, session, int(call.data.split(":")[2]))
+    if not sub:
+        return
+    decision = await contrib.approve(call.bot, session, sub)
+    if not decision.ok:
+        await call.answer(decision.text, show_alert=True)
+        return
+    await call.answer()
+    await _finish(call, session, decision.text)
+
+
+@router.callback_query(F.data.startswith("qq:p:"))
+async def replace(call: CallbackQuery, session: AsyncSession) -> None:
+    sub = await _pending(call, session, int(call.data.split(":")[2]))
+    if not sub:
+        return
+    decision = await contrib.approve(call.bot, session, sub, replace_id=sub.dup_of)
+    if not decision.ok:
+        await call.answer(decision.text, show_alert=True)
+        return
+    await call.answer()
+    await _finish(call, session, decision.text + f"\n(replaced #{sub.dup_of})")
+
+
+@router.callback_query(F.data.startswith("qq:r:"))
+async def reject_menu(call: CallbackQuery, session: AsyncSession) -> None:
+    sub = await _pending(call, session, int(call.data.split(":")[2]))
+    if not sub:
+        return
+    rows = [[_b(REASON_LABEL[r], f"qq:x:{sub.id}:{r}")] for r in K.REJECT_REASONS]
+    rows.append([_b("↩ Back", f"qq:b:{sub.id}")])
+    await call.answer()
+    await call.message.edit_reply_markup(reply_markup=InlineKeyboardMarkup(inline_keyboard=rows))
+
+
+@router.callback_query(F.data.startswith("qq:x:"))
+async def reject(call: CallbackQuery, session: AsyncSession) -> None:
+    _, _, sid, reason = call.data.split(":")
+    sub = await _pending(call, session, int(sid))
+    if not sub:
+        return
+    decision = await contrib.reject(call.bot, session, sub, reason)
+    await call.answer()
+    await _finish(call, session, decision.text)
+
+
+@router.callback_query(F.data.startswith("qq:b:"))
+async def back(call: CallbackQuery, session: AsyncSession) -> None:
+    sub = await _pending(call, session, int(call.data.split(":")[2]))
+    if sub:
+        await call.answer()
+        await _rerender(call, session, sub)
+
+
+@router.callback_query(F.data.startswith("qq:k:"))
+async def skip(call: CallbackQuery, session: AsyncSession) -> None:
+    sid = int(call.data.split(":")[2])
+    _skipped.setdefault(call.from_user.id, set()).add(sid)
+    await call.answer()
+    await _finish(call, session, f"⏭ Skipped #{sid} (use /queue to see it again).")
+
+
+@router.callback_query(F.data.startswith("qq:c:"))
+async def course_menu(call: CallbackQuery, session: AsyncSession) -> None:
+    sub = await _pending(call, session, int(call.data.split(":")[2]))
+    if not sub:
+        return
+    ranked = C.rank_courses(await lib.all_courses_cached(session), [(sub.file_name or "", "name")])
+    rows = [[_b(f"📘 {_course_label(c)}"[:60], f"qq:s:{sub.id}:{c.id}")] for _, c in ranked[:5]]
+    rows.append([_b("📚 All courses", f"qq:l:{sub.id}:0")])
+    rows.append([_b("↩ Back", f"qq:b:{sub.id}")])
+    await call.answer()
+    await call.message.edit_reply_markup(reply_markup=InlineKeyboardMarkup(inline_keyboard=rows))
+
+
+@router.callback_query(F.data.startswith("qq:l:"))
+async def all_courses(call: CallbackQuery, session: AsyncSession) -> None:
+    _, _, sid, page = call.data.split(":")
+    sub = await _pending(call, session, int(sid))
+    if not sub:
+        return
+    page = int(page)
+    courses = await lib.all_courses_cached(session)
+    rows = [[_b(f"📘 {_course_label(c)}"[:60], f"qq:s:{sub.id}:{c.id}")] for c in courses[page * PAGE : (page + 1) * PAGE]]
+    nav = []
+    if page > 0:
+        nav.append(_b("⬅️", f"qq:l:{sub.id}:{page - 1}"))
+    if (page + 1) * PAGE < len(courses):
+        nav.append(_b("➡️", f"qq:l:{sub.id}:{page + 1}"))
+    if nav:
+        rows.append(nav)
+    rows.append([_b("↩ Back", f"qq:b:{sub.id}")])
+    await call.answer()
+    await call.message.edit_reply_markup(reply_markup=InlineKeyboardMarkup(inline_keyboard=rows))
+
+
+@router.callback_query(F.data.startswith("qq:s:"))
+async def set_course(call: CallbackQuery, session: AsyncSession) -> None:
+    _, _, sid, cid = call.data.split(":")
+    sub = await _pending(call, session, int(sid))
+    material = await lib_repo.get_material(session, sub.material_id) if sub else None
+    if not sub or not material:
+        return
+    material.course_id = int(cid)
+    await call.answer("Course set")
+    await _rerender(call, session, sub)

app/bot/handlers/contribute.py

@@ -0,0 +1,233 @@
+"""Students giving files: a clear panel, a short window to send files, instant feedback.
+Nothing a student sends is visible to others until an admin approves it."""
+import time
+from typing import Optional
+
+from aiogram import F, Router
+from aiogram.types import CallbackQuery, InlineKeyboardButton, InlineKeyboardMarkup, Message
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.bot.keyboards import library as lib_kb
+from app.config import get_settings
+from app.core.i18n import all_translations, t
+from app.db.models import User
+from app.db.repos import library as lib_repo
+from app.db.repos import submissions as sub_repo
+from app.services import contrib_rules as K
+from app.services import contributions as contrib
+from app.services import library as lib
+from app.services.classifier import display_title
+
+router = Router()
+router.message.filter(F.chat.type == "private")
+WINDOW = 600  # seconds the "send me files now" window stays open
+_mode: dict[int, dict] = {}  # user_id -> {"until": monotonic, "course_id": Optional[int]}
+
+
+def _btn(text: str, data: str) -> InlineKeyboardButton:
+    return InlineKeyboardButton(text=text, callback_data=data)
+
+
+def _open_window(user_id: int, course_id: Optional[int] = None) -> None:
+    _mode[user_id] = {"until": time.monotonic() + WINDOW, "course_id": course_id}
+
+
+def _window(user_id: int) -> Optional[dict]:
+    mode = _mode.get(user_id)
+    return mode if mode and mode["until"] > time.monotonic() else None
+
+
+def _reason_text(lang: str, reason: Optional[str]) -> str:
+    if not reason:
+        return ""
+    return t(lang, f"contrib_reason_{reason}", days=get_settings().contribution_min_days)
+
+
+def _badge_line(lang: str, approved: int) -> str:
+    tier = K.badge_for(approved)
+    return f"\n🏷 {t(lang, f'badge_{tier}')}" if tier else ""
+
+
+async def _panel(user: User, session: AsyncSession) -> tuple[str, InlineKeyboardMarkup]:
+    cfg, lang = get_settings(), user.lang
+    approved, pending, _ = await sub_repo.stats_for(session, user.id)
+    reason = await contrib.check_eligibility(session, user)
+    nxt = K.next_badge(approved)
+    hint = f"\n🎯 {t(lang, 'contrib_next_badge', n=nxt[0], badge=t(lang, f'badge_{nxt[1]}'))}" if nxt else ""
+    text = t(
+        lang, "contrib_panel", xp=cfg.contribution_xp, bonus=cfg.contribution_bonus_xp, cap=cfg.contribution_weekly_cap,
+        approved=approved, pending=pending, badge=_badge_line(lang, approved) + hint, reason=_reason_text(lang, reason),
+    )
+    credit = t(lang, "contrib_credit_on" if user.credit_name else "contrib_credit_off")
+    kb = InlineKeyboardMarkup(inline_keyboard=[
+        [_btn(t(lang, "contrib_btn_go"), "ct:go")],
+        [_btn(t(lang, "contrib_btn_wanted"), "ct:wanted")],
+        [_btn(credit, "ct:credit")],
+    ])
+    return text, kb
+
+
+@router.message(F.text.in_(all_translations("btn_contribute")))
+async def open_panel(message: Message, user: User, session: AsyncSession) -> None:
+    if not get_settings().contributions_enabled:
+        await message.answer(t(user.lang, "soon"))
+        return
+    text, kb = await _panel(user, session)
+    await message.answer(text, reply_markup=kb)
+
+
+@router.callback_query(F.data == "ct:credit")
+async def toggle_credit(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    user.credit_name = not user.credit_name
+    await call.answer(t(user.lang, "contrib_credit_saved_on" if user.credit_name else "contrib_credit_saved_off"))
+    text, kb = await _panel(user, session)
+    if call.message:
+        try:
+            await call.message.edit_text(text, reply_markup=kb)
+        except Exception:
+            pass
+
+
+@router.callback_query(F.data == "ct:go")
+async def go(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    reason = await contrib.check_eligibility(session, user)
+    if reason:
+        await call.answer(_reason_text(user.lang, reason).strip()[:190], show_alert=True)
+        return
+    _open_window(user.id)
+    await call.answer()
+    await call.message.answer(t(user.lang, "contrib_send_now"))
+
+
+@router.callback_query(F.data == "ct:wanted")
+async def wanted(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    items = await contrib.wanted_courses(session, user)
+    await call.answer()
+    if not items:
+        await call.message.answer(t(user.lang, "contrib_wanted_none"))
+        return
+    rows = [[_btn(f"📘 {lib_kb.course_label(c)} · {n}", f"ct:w:{c.id}")] for c, n in items]
+    await call.message.answer(t(user.lang, "contrib_wanted"), reply_markup=InlineKeyboardMarkup(inline_keyboard=rows))
+
+
+@router.callback_query(F.data.startswith("ct:w:"))
+async def wanted_pick(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    reason = await contrib.check_eligibility(session, user)
+    if reason:
+        await call.answer(_reason_text(user.lang, reason).strip()[:190], show_alert=True)
+        return
+    course = await lib_repo.get_course(session, int(call.data.split(":")[2]))
+    if not course:
+        await call.answer(t(user.lang, "file_missing"), show_alert=True)
+        return
+    _open_window(user.id, course.id)
+    await call.answer()
+    await call.message.answer(t(user.lang, "contrib_send_now_course", course=course.name))
+
+
+# ---------------------------------------------------------------- receiving files
+@router.message(F.chat.type == "private", F.document | F.photo | F.video | F.audio)
+async def receive(message: Message, user: User, session: AsyncSession) -> None:
+    lang = user.lang
+    if not get_settings().contributions_enabled:
+        return
+    mode = _window(user.id)
+    if mode is None:
+        await message.answer(t(lang, "contrib_tap_first"))
+        return
+    reason = await contrib.check_eligibility(session, user)
+    if reason:
+        await message.answer(_reason_text(lang, reason).strip())
+        return
+    doc = message.document
+    if doc is None:
+        await message.answer(t(lang, "contrib_not_doc"))
+        return
+    problem = K.check_file(doc.file_name, doc.file_size)
+    if problem:
+        await message.answer(t(lang, "contrib_too_big" if problem == "size" else "contrib_not_doc"))
+        return
+
+    forced = await lib_repo.get_course(session, mode["course_id"]) if mode["course_id"] else None
+    result = await contrib.submit_file(
+        message.bot, session, user, file_id=doc.file_id, unique_id=doc.file_unique_id, file_name=doc.file_name,
+        size=doc.file_size, caption=message.caption, forced_course=forced,
+    )
+    _open_window(user.id, mode["course_id"])  # keep the window open for the next file
+
+    if result.kind == "duplicate":
+        title = display_title(result.duplicate_of.title) if result.duplicate_of else ""
+        await message.answer(t(lang, "contrib_dup", title=title))
+        return
+
+    m, sub = result.material, result.submission
+    title = display_title(m.title)
+    if result.kind == "need_course":
+        rows = [
+            [_btn(f"📘 {lib_kb.course_label(c)}", f"ct:c:{sub.id}:{c.id}")] for c in result.suggestions
+        ]
+        rows.append([_btn(t(lang, "contrib_more_courses"), f"ct:more:{sub.id}:0")])
+        await message.answer(t(lang, "contrib_need_course", title=title), reply_markup=InlineKeyboardMarkup(inline_keyboard=rows))
+        return
+
+    cfg = get_settings()
+    course = await lib_repo.get_course(session, m.course_id)
+    sparse = await lib_repo.ok_file_count(session, m.course_id) < K.SPARSE_COURSE_FILES
+    await message.answer(
+        t(
+            lang, "contrib_accepted", title=title, course=course.name if course else "", kind=t(lang, f"kind_{m.kind}"),
+            xp=cfg.contribution_xp, bonus=t(lang, "contrib_bonus", n=cfg.contribution_bonus_xp) if sparse else "",
+            note=t(lang, "contrib_near_note") if sub.dup_of else "",
+        ),
+        reply_markup=InlineKeyboardMarkup(inline_keyboard=[[_btn(t(lang, "contrib_change_course"), f"ct:more:{sub.id}:0")]]),
+    )
+
+
+# ---------------------------------------------------------------- course picking for a submission
+async def _own_pending(call: CallbackQuery, user: User, session: AsyncSession, sid: int):
+    sub = await sub_repo.get(session, sid)
+    if not sub or sub.user_id != user.id or sub.status != "pending":
+        await call.answer(t(user.lang, "file_missing"), show_alert=True)
+        return None, None
+    return sub, await lib_repo.get_material(session, sub.material_id)
+
+
+@router.callback_query(F.data.startswith("ct:c:"))
+async def set_course(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    _, _, sid, cid = call.data.split(":")
+    sub, material = await _own_pending(call, user, session, int(sid))
+    course = await lib_repo.get_course(session, int(cid))
+    if not sub or not material or not course:
+        return
+    material.course_id = course.id
+    await call.answer()
+    text = t(user.lang, "contrib_course_set", title=display_title(material.title), course=course.name)
+    try:
+        await call.message.edit_text(text)
+    except Exception:
+        await call.message.answer(text)
+
+
+@router.callback_query(F.data.startswith("ct:more:"))
+async def more_courses(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    _, _, sid, page = call.data.split(":")
+    sub, material = await _own_pending(call, user, session, int(sid))
+    if not sub:
+        return
+    page = int(page)
+    items = await lib_repo.list_courses(session, user.stream, user.year, page * lib.PAGE_SIZE, lib.PAGE_SIZE)
+    total = await lib_repo.count_courses(session, user.stream, user.year)
+    rows = [[_btn(f"📘 {lib_kb.course_label(c)}", f"ct:c:{sub.id}:{c.id}")] for c in items]
+    nav = []
+    if page > 0:
+        nav.append(_btn(t(user.lang, "btn_prev"), f"ct:more:{sub.id}:{page - 1}"))
+    if (page + 1) * lib.PAGE_SIZE < total:
+        nav.append(_btn(t(user.lang, "btn_next"), f"ct:more:{sub.id}:{page + 1}"))
+    if nav:
+        rows.append(nav)
+    await call.answer()
+    text = t(user.lang, "contrib_need_course", title=display_title(material.title) if material else "")
+    try:
+        await call.message.edit_text(text, reply_markup=InlineKeyboardMarkup(inline_keyboard=rows))
+    except Exception:
+        pass

app/bot/handlers/menu.py

@@ -8,7 +8,9 @@ from app.config import get_settings
 from app.core import season
 from app.core.i18n import all_translations, t
 from app.db.models import User
+from app.db.repos import submissions as sub_repo
 from app.db.repos import users as users_repo
+from app.services import contrib_rules as K
 from app.services import growth
 from app.services import referrals as referral_service
 from app.services import xp_rules as R
@@ -50,6 +52,9 @@ async def profile(message: Message, user: User, session: AsyncSession) -> None:
     level, needed = R.level_for(user.points or 0)
     count, qualified = await referral_service.stats(session, user)
     rank = await users_repo.week_rank(session, user, week)
+    approved = await sub_repo.approved_count(session, user.id)
+    tier = K.badge_for(approved)
+    badge = f"\n🏷 {t(lang, f'badge_{tier}')} ({approved})" if tier else ""
     await message.answer(
         t(
             lang,
@@ -67,6 +72,7 @@ async def profile(message: Message, user: User, session: AsyncSession) -> None:
             best=user.best_streak,
             refs=count,
             refs_q=qualified,
+            badge=badge,
         )
     )
 

app/bot/keyboards/common.py

@@ -50,7 +50,7 @@ def main_menu(lang: str) -> ReplyKeyboardMarkup:
 
     return ReplyKeyboardMarkup(
         keyboard=[
-            [b("btn_library")],
+            [b("btn_library"), b("btn_contribute")],
             [b("btn_profile"), b("btn_top")],
             [b("btn_gpa"), b("btn_invite")],
             [b("btn_lang")],

app/config.py

@@ -32,6 +32,15 @@ class Settings(BaseSettings):
     def watermark_link(self) -> str:
         return self.watermark_url or f"https://t.me/{self.gate_channel.lstrip('@')}"
 
+    # --- student file contributions ---
+    contributions_enabled: bool = True
+    contribution_xp: int = 20
+    contribution_bonus_xp: int = 5  # extra when the course is short of material
+    contribution_weekly_cap: int = 5  # rewarded files per student per week
+    contribution_min_days: int = 2  # active days before a student may submit
+    contribution_pending_limit: int = 5
+    contribution_daily_limit: int = 8
+
     # --- weekly season / prizes (money is OFF until you switch it on) ---
     prizes_enabled: bool = False
     prize_top: str = "50,30,20"  # birr airtime card for rank 1,2,3 (comma separated)

app/core/notify.py

@@ -7,15 +7,15 @@ from app.config import get_settings
 log = logging.getLogger(__name__)
 
 
-async def safe_send(bot: Bot, chat_id: int, text: str) -> bool:
+async def safe_send(bot: Bot, chat_id: int, text: str, reply_markup=None) -> bool:
     try:
-        await bot.send_message(chat_id, text)
+        await bot.send_message(chat_id, text, reply_markup=reply_markup)
         return True
     except Exception as exc:
         log.info("Could not message %s: %r", chat_id, exc)
         return False
 
 
-async def notify_admins(bot: Bot, text: str) -> None:
+async def notify_admins(bot: Bot, text: str, reply_markup=None) -> None:
     for admin_id in get_settings().admin_id_set:
-        await safe_send(bot, admin_id, text[:4000])
+        await safe_send(bot, admin_id, text[:4000], reply_markup=reply_markup)

app/db/migrate.py

@@ -39,6 +39,8 @@ POSTGRES_UPGRADES = [
     "ALTER TABLE users ADD COLUMN IF NOT EXISTS source VARCHAR(24)",
     "ALTER TABLE users ADD COLUMN IF NOT EXISTS pending_link VARCHAR(16)",
     "ALTER TABLE users ADD COLUMN IF NOT EXISTS share_prompt_day VARCHAR(10)",
+    "ALTER TABLE users ADD COLUMN IF NOT EXISTS credit_name BOOLEAN NOT NULL DEFAULT FALSE",
+    "ALTER TABLE materials ADD COLUMN IF NOT EXISTS credit VARCHAR(40)",
     "ALTER TABLE referrals ADD COLUMN IF NOT EXISTS qualified BOOLEAN NOT NULL DEFAULT FALSE",
 ]
 

app/db/models/__init__.py

@@ -3,7 +3,8 @@ from app.db.models.group import BotGroup
 from app.db.models.material import Material
 from app.db.models.pending import PendingMaterial
 from app.db.models.referral import Referral
+from app.db.models.submission import Submission
 from app.db.models.user import User
 from app.db.models.xp import SeasonResult, XpEvent
 
-__all__ = ["User", "Course", "Material", "Referral", "PendingMaterial", "XpEvent", "SeasonResult", "BotGroup"]
+__all__ = ["User", "Course", "Material", "Referral", "PendingMaterial", "XpEvent", "SeasonResult", "BotGroup", "Submission"]

app/db/models/material.py

@@ -31,6 +31,7 @@ class Material(Base):
     size: Mapped[Optional[int]] = mapped_column(Integer)
     source_name: Mapped[Optional[str]] = mapped_column(String(256))  # original file name
     status: Mapped[str] = mapped_column(String(8), default="ok", server_default="ok")  # ok | review
+    credit: Mapped[Optional[str]] = mapped_column(String(40))  # contributor name, if they chose to be credited
     downloads: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
     uploader_id: Mapped[Optional[int]] = mapped_column(BigInteger)
     library_chat_id: Mapped[Optional[int]] = mapped_column(BigInteger)

app/db/models/submission.py

@@ -0,0 +1,26 @@
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import BigInteger, Boolean, DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class Submission(Base):
+    """A file a student offered. The file itself is a Material with status 'pending' until approved."""
+
+    __tablename__ = "submissions"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(BigInteger, index=True)
+    material_id: Mapped[Optional[int]] = mapped_column(Integer, index=True)
+    file_name: Mapped[Optional[str]] = mapped_column(String(256))
+    status: Mapped[str] = mapped_column(String(10), default="pending", index=True)  # pending|approved|rejected
+    reason: Mapped[Optional[str]] = mapped_column(String(24))  # rejection reason code
+    note: Mapped[Optional[str]] = mapped_column(String(300))  # flags shown to the admin
+    dup_of: Mapped[Optional[int]] = mapped_column(Integer)  # existing material this one resembles
+    xp: Mapped[int] = mapped_column(Integer, default=0)
+    notified: Mapped[bool] = mapped_column(Boolean, default=False)  # admin already told about it
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    reviewed_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))

app/db/models/user.py

@@ -31,5 +31,6 @@ class User(Base):
     source: Mapped[Optional[str]] = mapped_column(String(24))  # where they came from (poster, inline, referral...)
     pending_link: Mapped[Optional[str]] = mapped_column(String(16))  # deep link to open after joining/onboarding
     share_prompt_day: Mapped[Optional[str]] = mapped_column(String(10))  # last day we suggested sharing
+    credit_name: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")  # name on files they give
     is_banned: Mapped[bool] = mapped_column(Boolean, default=False)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

app/db/repos/library.py

@@ -277,6 +277,15 @@ async def unstamped_pdfs(session: AsyncSession, limit: int, max_size: int) -> li
     return list(res.scalars())
 
 
+async def ok_file_count(session: AsyncSession, course_id: int) -> int:
+    res = await session.execute(
+        select(func.count()).select_from(Material).where(
+            Material.course_id == course_id, Material.file_id.is_not(None), Material.status == "ok"
+        )
+    )
+    return int(res.scalar_one())
+
+
 async def count_course_files(session: AsyncSession, course_id: int) -> int:
     res = await session.execute(select(func.count()).select_from(Material).where(Material.course_id == course_id))
     return int(res.scalar_one())

app/db/repos/submissions.py

@@ -0,0 +1,84 @@
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import func, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Submission
+
+
+async def create(
+    session: AsyncSession, *, user_id: int, material_id: int, file_name: Optional[str],
+    note: Optional[str], dup_of: Optional[int],
+) -> Submission:
+    sub = Submission(
+        user_id=user_id, material_id=material_id, file_name=(file_name or "")[:250] or None,
+        note=(note or None) and note[:290], dup_of=dup_of,
+    )
+    session.add(sub)
+    await session.flush()
+    return sub
+
+
+async def get(session: AsyncSession, submission_id: int) -> Optional[Submission]:
+    return await session.get(Submission, submission_id)
+
+
+async def _count(session: AsyncSession, *conditions) -> int:
+    res = await session.execute(select(func.count()).select_from(Submission).where(*conditions))
+    return int(res.scalar_one())
+
+
+async def pending_count(session: AsyncSession, user_id: int) -> int:
+    return await _count(session, Submission.user_id == user_id, Submission.status == "pending")
+
+
+async def count_since(session: AsyncSession, user_id: int, since: datetime) -> int:
+    return await _count(session, Submission.user_id == user_id, Submission.created_at >= since)
+
+
+async def approved_count(session: AsyncSession, user_id: int) -> int:
+    return await _count(session, Submission.user_id == user_id, Submission.status == "approved")
+
+
+async def pending_total(session: AsyncSession) -> int:
+    return await _count(session, Submission.status == "pending")
+
+
+async def rejected_times(session: AsyncSession, user_id: int, since: datetime) -> list[datetime]:
+    res = await session.execute(
+        select(Submission.reviewed_at).where(
+            Submission.user_id == user_id, Submission.status == "rejected", Submission.reviewed_at >= since
+        )
+    )
+    return [d for d in res.scalars() if d is not None]
+
+
+async def next_pending(session: AsyncSession, skip: set[int]) -> Optional[Submission]:
+    stmt = select(Submission).where(Submission.status == "pending").order_by(Submission.id).limit(1)
+    if skip:
+        stmt = stmt.where(Submission.id.not_in(skip))
+    return (await session.execute(stmt)).scalar_one_or_none()
+
+
+async def unnotified(session: AsyncSession) -> list[Submission]:
+    res = await session.execute(
+        select(Submission).where(Submission.status == "pending", Submission.notified.is_(False)).order_by(Submission.id)
+    )
+    return list(res.scalars())
+
+
+async def mark_notified(session: AsyncSession, ids: list[int]) -> None:
+    if ids:
+        await session.execute(
+            update(Submission).where(Submission.id.in_(ids)).values(notified=True).execution_options(synchronize_session=False)
+        )
+
+
+async def stats_for(session: AsyncSession, user_id: int) -> tuple[int, int, int]:
+    """(approved, pending, rejected)"""
+    return (
+        await _count(session, Submission.user_id == user_id, Submission.status == "approved"),
+        await _count(session, Submission.user_id == user_id, Submission.status == "pending"),
+        await _count(session, Submission.user_id == user_id, Submission.status == "rejected"),
+    )

app/main.py

@@ -9,7 +9,7 @@ from app.bot.loader import build_dispatcher
 from app.config import get_settings
 from app.core.logging import setup_logging
 from app.db.session import init_db, keepalive, warm_up
-from app.tasks.jobs import close_previous_week, periodic, qualify_referrals
+from app.tasks.jobs import close_previous_week, notify_pending_submissions, periodic, qualify_referrals
 
 log = logging.getLogger(__name__)
 
@@ -27,6 +27,7 @@ async def run_bot_forever() -> None:
         asyncio.create_task(keepalive()),
         asyncio.create_task(periodic("referrals", 1800, qualify_referrals, bot)),
         asyncio.create_task(periodic("season", 600, close_previous_week, bot)),
+        asyncio.create_task(periodic("submissions", 120, notify_pending_submissions, bot, first_delay=90)),
     ]
     try:
         while True:

app/services/contrib_rules.py

@@ -0,0 +1,71 @@
+"""Rules for student contributions. Pure, so every rule is unit-tested."""
+import os
+from datetime import datetime, timedelta
+from typing import Optional, Sequence
+
+ALLOWED_EXT = (".pdf", ".pptx", ".docx")
+MAX_BYTES = 20 * 1024 * 1024  # the bot can only read files up to 20 MB (needed for duplicate checks + stamping)
+BLOCK_AFTER_REJECTIONS = 3
+REJECTION_WINDOW_DAYS = 14
+BLOCK_DAYS = 7
+SPARSE_COURSE_FILES = 3  # a course with fewer files than this counts as "wanted"
+BADGES = ((15, "gold"), (5, "silver"), (1, "bronze"))  # approved files needed -> badge
+REJECT_REASONS = ("duplicate", "quality", "notallowed")
+
+
+def check_file(file_name: Optional[str], size: Optional[int]) -> Optional[str]:
+    """None = fine, else a reason code ('ext' | 'size')."""
+    if os.path.splitext(file_name or "")[1].lower() not in ALLOWED_EXT:
+        return "ext"
+    if size is None or size > MAX_BYTES:
+        return "size"
+    return None
+
+
+def blocked_until(rejected_at: Sequence[datetime], now: datetime) -> Optional[datetime]:
+    """3 rejections inside 14 days -> no new submissions for 7 days after the last one."""
+    recent = sorted(d for d in rejected_at if d >= now - timedelta(days=REJECTION_WINDOW_DAYS))
+    if len(recent) < BLOCK_AFTER_REJECTIONS:
+        return None
+    until = recent[-1] + timedelta(days=BLOCK_DAYS)
+    return until if until > now else None
+
+
+def eligibility(
+    *, active_days: int, min_days: int, pending: int, pending_limit: int, today: int, daily_limit: int,
+    blocked: Optional[datetime],
+) -> Optional[str]:
+    """None = may submit, else a reason code."""
+    if active_days < min_days:
+        return "new"
+    if blocked is not None:
+        return "blocked"
+    if pending >= pending_limit:
+        return "pending"
+    if today >= daily_limit:
+        return "daily"
+    return None
+
+
+def badge_for(approved: int) -> Optional[str]:
+    for needed, tier in BADGES:
+        if approved >= needed:
+            return tier
+    return None
+
+
+def next_badge(approved: int) -> Optional[tuple[int, str]]:
+    """(files still needed, tier) for the next badge, or None at the top."""
+    for needed, tier in reversed(BADGES):
+        if approved < needed:
+            return needed - approved, tier
+    return None
+
+
+def reward(
+    *, rewarded_this_week: int, course_files_before: int, xp: int, bonus: int, weekly_cap: int
+) -> tuple[int, int]:
+    """(XP, bonus XP). Nothing once the weekly cap is used; the bonus is for courses that are short of material."""
+    if rewarded_this_week >= weekly_cap:
+        return 0, 0
+    return xp, (bonus if course_files_before < SPARSE_COURSE_FILES else 0)

app/services/contributions.py

@@ -0,0 +1,173 @@
+"""Student contributions: submit -> admin review -> approve (stamp, publish, reward) or reject (explain)."""
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from aiogram import Bot
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import get_settings
+from app.core import season
+from app.core.i18n import t
+from app.core.notify import safe_send
+from app.db.models import Material, Submission, User
+from app.db.repos import library as lib_repo
+from app.db.repos import submissions as sub_repo
+from app.db.repos import users as users_repo
+from app.db.repos import xp as xp_repo
+from app.services import contrib_rules as K
+from app.services import library as library_service
+from app.services import smart_ingest
+from app.services import xp as xp_service
+
+log = logging.getLogger(__name__)
+
+
+# ------------------------------------------------------------------ student side
+async def check_eligibility(session: AsyncSession, user: User) -> Optional[str]:
+    """None = may submit now, else a reason code (new | blocked | pending | daily)."""
+    cfg = get_settings()
+    now = datetime.now(timezone.utc)
+    rejected = await sub_repo.rejected_times(session, user.id, now - timedelta(days=K.REJECTION_WINDOW_DAYS))
+    return K.eligibility(
+        active_days=user.active_days or 0,
+        min_days=cfg.contribution_min_days,
+        pending=await sub_repo.pending_count(session, user.id),
+        pending_limit=cfg.contribution_pending_limit,
+        today=await sub_repo.count_since(session, user.id, now - timedelta(hours=24)),
+        daily_limit=cfg.contribution_daily_limit,
+        blocked=K.blocked_until(rejected, now),
+    )
+
+
+@dataclass
+class SubmitResult:
+    kind: str  # duplicate | accepted | need_course
+    submission: Optional[Submission] = None
+    material: Optional[Material] = None
+    outcome: Optional[smart_ingest.Outcome] = None
+    duplicate_of: Optional[Material] = None
+    suggestions: list = field(default_factory=list)
+
+
+async def submit_file(
+    bot: Bot, session: AsyncSession, user: User, *, file_id: str, unique_id: str,
+    file_name: Optional[str], size: Optional[int], caption: Optional[str], forced_course=None,
+) -> SubmitResult:
+    out = await smart_ingest.ingest_file(
+        bot, session, uploader_id=user.id, file_type="document", file_id=file_id, unique_id=unique_id,
+        file_name=file_name, size=size, caption=caption, forced_course=forced_course,
+        backup_channel=0, message=None, stamp=False,  # stamped only when an admin approves it
+    )
+    if out.status == "duplicate":
+        return SubmitResult("duplicate", duplicate_of=out.duplicate_of, outcome=out)
+    material = out.material
+    material.status = "pending"  # invisible to students until approved
+    flags = list(out.notes)
+    dup_of = None
+    if out.status == "near_duplicate" and out.duplicate_of is not None:
+        dup_of = out.duplicate_of.id
+        flags.append(f"near-duplicate of #{dup_of} “{out.duplicate_of.title[:40]}”")
+    if material.course_id is None:
+        flags.append("course unknown")
+    sub = await sub_repo.create(
+        session, user_id=user.id, material_id=material.id, file_name=file_name, note="; ".join(flags), dup_of=dup_of
+    )
+    kind = "need_course" if material.course_id is None else "accepted"
+    return SubmitResult(kind, submission=sub, material=material, outcome=out, suggestions=out.suggestions)
+
+
+async def wanted_courses(session: AsyncSession, user: User, limit: int = 8) -> list[tuple[object, int]]:
+    """Courses (for this student's stream/year) with the fewest files first, only those short of material."""
+    counts = await lib_repo.file_counts(session)
+    courses = await lib_repo.list_courses(session, user.stream, user.year, 0, 200, only_with_files=False)
+    short = [(c, counts.get(c.id, 0)) for c in courses if counts.get(c.id, 0) < K.SPARSE_COURSE_FILES]
+    short.sort(key=lambda item: (item[1], item[0].id))
+    return short[:limit]
+
+
+# ------------------------------------------------------------------ admin side
+@dataclass
+class Decision:
+    ok: bool
+    text: str
+
+
+async def approve(
+    bot: Bot, session: AsyncSession, sub: Submission, *, replace_id: Optional[int] = None
+) -> Decision:
+    cfg = get_settings()
+    material = await lib_repo.get_material(session, sub.material_id) if sub.material_id else None
+    if material is None:
+        sub.status, sub.reviewed_at, sub.reason = "rejected", datetime.now(timezone.utc), "gone"
+        return Decision(False, "That file no longer exists.")
+    if material.course_id is None:
+        return Decision(False, "Pick a course first.")
+
+    submitter = await users_repo.get(session, sub.user_id)
+    files_before = await lib_repo.ok_file_count(session, material.course_id)
+
+    stamp_note = ""
+    if cfg.watermark_enabled and (material.source_name or "").lower().endswith(".pdf") and not material.watermarked:
+        target = cfg.library_channel_id or (next(iter(cfg.admin_id_set), None) or sub.user_id)
+        ok, reason = await smart_ingest.stamp_existing(bot, material, target)
+        stamp_note = " · 🔖 stamped" if ok else f" · not stamped ({reason})"
+
+    if replace_id:
+        old = await lib_repo.get_material(session, replace_id)
+        if old:
+            material.downloads = (material.downloads or 0) + (old.downloads or 0)
+            await lib_repo.delete_material(session, old.id)
+    material.status = "ok"
+    if submitter and submitter.credit_name:
+        material.credit = (submitter.full_name or "").strip().split(" ")[0][:40] or None
+
+    gained = 0
+    badge_tier = None
+    if submitter:
+        rewarded = await xp_repo.count_kind_in_week(session, submitter.id, "contribution", season.week_key())
+        xp, bonus = K.reward(
+            rewarded_this_week=rewarded, course_files_before=files_before, xp=cfg.contribution_xp,
+            bonus=cfg.contribution_bonus_xp, weekly_cap=cfg.contribution_weekly_cap,
+        )
+        main = await xp_service.award(session, submitter, "contribution", xp, ref=f"sub{sub.id}", capped=False)
+        extra = await xp_service.award(session, submitter, "contribution_bonus", bonus, ref=f"subb{sub.id}", capped=False)
+        gained = main.amount + extra.amount
+        session.sync_session.info.setdefault("invalidate", set()).add(submitter.id)
+    sub.status, sub.reviewed_at, sub.xp = "approved", datetime.now(timezone.utc), gained
+    session.sync_session.info["wrote"] = True
+    await session.flush()
+    library_service.invalidate_courses()
+
+    if submitter:
+        approved_total = await sub_repo.approved_count(session, submitter.id)
+        course = await lib_repo.get_course(session, material.course_id)
+        await safe_send(
+            bot, submitter.id,
+            t(submitter.lang, "contrib_approved", title=material.title, course=course.name if course else "", xp=gained),
+        )
+        badge_tier = K.badge_for(approved_total) if approved_total in {n for n, _ in K.BADGES} else None
+        if badge_tier:
+            await safe_send(bot, submitter.id, t(submitter.lang, "contrib_badge", badge=t(submitter.lang, f"badge_{badge_tier}")))
+    return Decision(True, f"✅ Approved #{material.id} “{material.title}” (+{gained} XP{stamp_note})")
+
+
+async def reject(bot: Bot, session: AsyncSession, sub: Submission, reason: str) -> Decision:
+    reason = reason if reason in K.REJECT_REASONS else "quality"
+    material = await lib_repo.get_material(session, sub.material_id) if sub.material_id else None
+    title = material.title if material else (sub.file_name or "")
+    if material:
+        await lib_repo.delete_material(session, material.id)
+    now = datetime.now(timezone.utc)
+    sub.status, sub.reason, sub.reviewed_at = "rejected", reason, now
+    session.sync_session.info["wrote"] = True
+    await session.flush()
+    submitter = await users_repo.get(session, sub.user_id)
+    if submitter:
+        text = t(submitter.lang, f"contrib_rejected_{reason}", title=title)
+        rejected = await sub_repo.rejected_times(session, submitter.id, now - timedelta(days=K.REJECTION_WINDOW_DAYS))
+        if K.blocked_until(rejected, now):
+            text += t(submitter.lang, "contrib_blocked_notice")
+        await safe_send(bot, submitter.id, text)
+    return Decision(True, f"🗑 Rejected ({reason}): “{title}”")

app/services/library.py

@@ -83,6 +83,8 @@ async def send_material(bot: Bot, chat_id: int, material: Material, course: Opti
     caption = f"📄 {fuzzy_display(material.title)}"
     if course:
         caption += f"\n📚 {course.name}"
+    if material.credit:
+        caption += f"\n✍️ {material.credit}"
     caption += f"\n#{material.kind}"
     caption += f"\n🤖 @{(await bot.me()).username}"
     kwargs = {material.file_type: material.file_id, "caption": caption}

app/services/qr.py

@@ -0,0 +1,31 @@
+"""QR codes as PNG images (for Canva, stickers, social posts) using only reportlab's encoder + Pillow."""
+import io
+
+from PIL import Image, ImageDraw
+from reportlab.graphics.barcode import qrencoder
+
+
+def qr_matrix(data: str) -> list[list[bool]]:
+    qr = qrencoder.QRCode(None, qrencoder.QRErrorCorrectLevel.M)  # None = pick the smallest version that fits
+    qr.addData(data)
+    qr.make()
+    n = qr.getModuleCount()
+    return [[bool(qr.isDark(r, c)) for c in range(n)] for r in range(n)]
+
+
+def qr_png(data: str, *, box: int = 26, border: int = 4, transparent: bool = False) -> bytes:
+    """Black modules on white (or transparent) with the 4-module quiet zone scanners need."""
+    matrix = qr_matrix(data)
+    n = len(matrix)
+    size = (n + 2 * border) * box
+    mode, bg, fg = ("RGBA", (0, 0, 0, 0), (0, 0, 0, 255)) if transparent else ("RGB", (255, 255, 255), (0, 0, 0))
+    img = Image.new(mode, (size, size), bg)
+    draw = ImageDraw.Draw(img)
+    for r, row in enumerate(matrix):
+        for c, dark in enumerate(row):
+            if dark:
+                x, y = (c + border) * box, (r + border) * box
+                draw.rectangle([x, y, x + box - 1, y + box - 1], fill=fg)
+    out = io.BytesIO()
+    img.save(out, format="PNG")
+    return out.getvalue()

app/services/smart_ingest.py

@@ -62,6 +62,7 @@ async def ingest_file(
     forced_title: Optional[str] = None,
     backup_channel: int = 0,
     message=None,
+    stamp: bool = True,
 ) -> Outcome:
     # 1) exact same Telegram file
     existing = await repo.find_by_unique_id(session, unique_id)
@@ -128,7 +129,7 @@ async def ingest_file(
     # 7b) stamp PDFs with the official channel link; students receive the STAMPED copy
     stored_file_id, orig_file_id, stamped_ok = file_id, None, False
     library_chat = library_msg = None
-    if get_settings().watermark_enabled and ext == ".pdf" and file_type == "document":
+    if stamp and get_settings().watermark_enabled and ext == ".pdf" and file_type == "document":
         if data is None:
             big = size is not None and size > BOT_API_DOWNLOAD_LIMIT
             notes.append("not watermarked: over 20 MB, the bot cannot read it" if big else "not watermarked: could not read the file")
@@ -187,3 +188,23 @@ async def ingest_file(
         status, material=material, course=course, kind=kind, title=material.title, why=why,
         notes=notes, suggestions=suggestions, duplicate_of=near, file_name=file_name,
     )
+
+
+async def stamp_existing(bot: Bot, material: Material, target_chat: int) -> tuple[bool, str]:
+    """Stamp a PDF that is already stored (a student's file at approval time). (ok, reason when not ok)"""
+    data = await _download(bot, material.orig_file_id or material.file_id)
+    if not data:
+        return False, "could not download"
+    stamped, reason = await wm.stamp(data, wm.current_style())
+    if stamped is None:
+        return False, reason
+    try:
+        sent = await bot.send_document(
+            target_chat, BufferedInputFile(stamped, filename=material.source_name or "document.pdf"),
+            caption=f"📌 {material.title}"[:200], disable_notification=True,
+        )
+    except Exception as exc:
+        return False, f"upload failed: {type(exc).__name__}"
+    material.orig_file_id = material.orig_file_id or material.file_id
+    material.file_id, material.watermarked = sent.document.file_id, True
+    return True, ""

app/services/users.py

@@ -13,7 +13,7 @@ SNAPSHOT_COLS = (
     "id", "username", "full_name", "lang", "stream", "year", "referred_by",
     "gate_passed", "points", "streak", "best_streak", "last_active_on", "is_banned",
     "active_days", "week_key", "week_xp", "day_key", "day_xp", "trust",
-    "source", "pending_link", "share_prompt_day",
+    "source", "pending_link", "share_prompt_day", "credit_name",
 )
 
 

app/tasks/jobs.py

@@ -4,11 +4,13 @@ import logging
 from datetime import datetime, timedelta, timezone
 
 from aiogram import Bot
+from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
 
 from app.core import cache, season
 from app.core.i18n import t
 from app.core.notify import notify_admins, safe_send
 from app.db.repos import referrals as ref_repo
+from app.db.repos import submissions as sub_repo
 from app.db.repos import users as users_repo
 from app.db.repos import xp as xp_repo
 from app.db.session import SessionFactory
@@ -82,6 +84,22 @@ async def close_previous_week(bot: Bot) -> None:
     await notify_admins(bot, summary)
 
 
+async def notify_pending_submissions(bot: Bot) -> None:
+    """Tell the admin about new student files in ONE message with a button that opens the review."""
+    async with SessionFactory() as session:
+        fresh = await sub_repo.unnotified(session)
+        if not fresh:
+            return
+        total = await sub_repo.pending_total(session)
+        await sub_repo.mark_notified(session, [s.id for s in fresh])
+        await session.commit()
+    await notify_admins(
+        bot,
+        f"📥 <b>{len(fresh)}</b> new file(s) from students · {total} waiting in total",
+        reply_markup=InlineKeyboardMarkup(inline_keyboard=[[InlineKeyboardButton(text="▶️ Review now", callback_data="qq:start")]]),
+    )
+
+
 async def periodic(name: str, interval: int, fn, bot: Bot, first_delay: int = 60) -> None:
     await asyncio.sleep(first_delay)
     while True:

locales/am.json

@@ -37,7 +37,7 @@
   "file_missing": "ይሄ ፋይል አልተገኘም 😕",
   "search_none": "🔍 ምንም አላገኘሁም። ሌላ ቃል ሞክሩ፣ ለምሳሌ የኮርሱን ስም ወይም ኮድ።",
   "search_results": "🔍 <b>ለ «{q}» ያገኘሁት</b>",
-  "profile_text": "👤 <b>{name}</b>\n🎓 {stream} · {year}\n\n🏅 ደረጃ {level}፦ <b>{title}</b>\n⭐ ጠቅላላ XP፦ <b>{points}</b> ({to_next})\n📅 የዚህ ሳምንት XP፦ <b>{week_xp}</b> · {week_rank}\n🔥 ተከታታይ ቀናት፦ <b>{streak}</b> (ከፍተኛው {best})\n👥 የጋበዛችኋቸው፦ <b>{refs}</b> (ንቁ {refs_q})",
+  "profile_text": "👤 <b>{name}</b>\n🎓 {stream} · {year}\n\n🏅 ደረጃ {level}፦ <b>{title}</b>\n⭐ ጠቅላላ XP፦ <b>{points}</b> ({to_next})\n📅 የዚህ ሳምንት XP፦ <b>{week_xp}</b> · {week_rank}\n🔥 ተከታታይ ቀናት፦ <b>{streak}</b> (ከፍተኛው {best})\n👥 የጋበዛችኋቸው፦ <b>{refs}</b> (ንቁ {refs_q}){badge}",
   "top_text": "🏆 <b>የሳምንቱ ደረጃ</b> · {days} ቀን ቀርቷል\n{rows}\n\n📍 እናንተ፦ <b>{rank}</b> · {week_xp} XP\n⚔️ {n_label}፦ <b>{natural}</b> · {s_label}፦ <b>{social}</b>{prize}\n\nℹ️ ህጎቹ፦ /rules",
   "inline_open_bot": "📚 ቦቱን ክፈቱ",
   "prize_block": "\n\n💰 <b>የሳምንቱ ሽልማት</b> (የሞባይል ካርድ)፦\n{lines}\n🎟 እጣ፦ {raffle} ብር (ለቀሩት ብቁ ተወዳዳሪዎች)\nለመወዳደር፦ በሳምንቱ ቢያንስ {days} ቀን መግባትና {xp} XP መሰብሰብ ያስፈልጋል",
@@ -69,5 +69,42 @@
   "group_find_result": "🔍 <b>ለ «{q}» ያገኘሁት</b>\nንኩና ቦቱ ውስጥ ክፈቱ 👇",
   "share_btn": "📤 ለጓደኛ አጋሩ",
   "share_text": "📚 ለDBU ተማሪዎች ነጻ ማቴሪያሎች፦ ስላይድ፣ የድሮ ፈተናዎች፣ ሞጁሎች — ሁሉም በአንድ ቦታ። እዚህ ጀምሩ 👇",
-  "share_prompt": "👍 ጠቀማችሁ? ለክፍል ጓደኞቻችሁም አጋሩላቸው፤ በሊንካችሁ ሲገቡ XP ታገኛላችሁ 🎁"
+  "share_prompt": "👍 ጠቀማችሁ? ለክፍል ጓደኞቻችሁም አጋሩላቸው፤ በሊንካችሁ ሲገቡ XP ታገኛላችሁ 🎁",
+  "btn_contribute": "📤 ፋይል አስገቡ",
+  "contrib_panel": "📤 <b>ፋይል አስገቡ</b>\nየሚጠቅም ማቴሪያል (ስላይድ፣ ሞጁል፣ የድሮ ፈተና፣ ኖት) አላችሁ? ላኩልን፣ ለሁሉም ተማሪ ይጠቅማል 🙌\n\n<b>ህጎች</b>\n• PDF፣ PPTX ወይም DOCX፣ እስከ 20 MB\n• የንግድ መጽሐፍ ወይም የሌላ ሰው የተከለከለ ይዘት አይሆንም\n• ተመሳሳይ ፋይል አስቀድሞ ካለ ወዲያው እነግራችኋለሁ\n• አድሚኑ ካየ በኋላ ነው ማቴሪያሎች ውስጥ የሚገባው\n\n🎁 ሲጸድቅ +{xp} XP (ፋይል የሚፈለግበት ኮርስ ከሆነ +{bonus} ጉርሻ)፣ በሳምንት እስከ {cap} ፋይል\n\n✅ የጸደቁ፦ <b>{approved}</b> · ⏳ በመጠባበቅ፦ <b>{pending}</b>{badge}{reason}",
+  "contrib_next_badge": "ለ{badge} {n} ፋይል ቀርቷል",
+  "contrib_btn_go": "📤 ፋይል ልላክ",
+  "contrib_btn_wanted": "🎯 የሚፈለጉ ኮርሶች",
+  "contrib_credit_on": "✍️ ስሜ ይጠቀስ: ✅",
+  "contrib_credit_off": "✍️ ስሜ ይጠቀስ: ❌",
+  "contrib_credit_saved_on": "እሺ፣ በሚጸድቁ ፋይሎች ላይ ስማችሁ ይጠቀሳል",
+  "contrib_credit_saved_off": "እሺ፣ ስማችሁ አይጠቀስም",
+  "contrib_send_now": "እሺ! አሁን ፋይሉን ላኩ 📎 (PDF፣ PPTX ወይም DOCX)።\nብዙ ፋይል አንድ በአንድ መላክ ትችላላችሁ፤ ለ10 ደቂቃ ክፍት ነው።",
+  "contrib_send_now_course": "እሺ! ለ<b>{course}</b> ፋይል ላኩ 📎 (PDF፣ PPTX ወይም DOCX)።\nለ10 ደቂቃ ክፍት ነው።",
+  "contrib_tap_first": "ፋይል ለማስገባት መጀመሪያ «📤 ፋይል አስገቡ» ንኩና «ፋይል ልላክ» ምረጡ 🙂",
+  "contrib_not_doc": "PDF፣ PPTX ወይም DOCX ብቻ ነው የምቀበለው 🙏",
+  "contrib_too_big": "ፋይሉ ከ20 MB ይበልጣል፤ ለሁለት ከፍላችሁ ላኩት።",
+  "contrib_dup": "♻️ ይሄ ፋይል አስቀድሞ ማቴሪያሎች ውስጥ አለ፦ «{title}»። ሌላ ካላችሁ ላኩ!",
+  "contrib_accepted": "✅ ተቀብያለሁ!\n📎 «{title}»\n📘 {course} · {kind}\n\nአድሚኑ ሲያጸድቀው ማቴሪያሎች ውስጥ ይገባል፤ +{xp} XP ታገኛላችሁ{bonus} 🎁{note}",
+  "contrib_bonus": " (+{n} ጉርሻ)",
+  "contrib_near_note": "\n🔍 ተመሳሳይ ፋይል ስላለ አድሚኑ ያጣራዋል።",
+  "contrib_need_course": "🤔 «{title}» የየትኛው ኮርስ ነው? ምረጡ 👇",
+  "contrib_course_set": "✅ «{title}» → {course}። አድሚኑ ሲያጸድቀው እነግራችኋለሁ።",
+  "contrib_more_courses": "🔎 ሌላ ኮርስ",
+  "contrib_change_course": "✏️ ኮርስ ቀይር",
+  "contrib_wanted": "🎯 <b>እነዚህ ኮርሶች ማቴሪያል ይፈልጋሉ</b>\nአንዱን ንኩና ፋይል ላኩ፤ ተጨማሪ ጉርሻ ታገኛላችሁ 🎁",
+  "contrib_wanted_none": "🎉 ሁሉም ኮርሶች በቂ ማቴሪያል አላቸው! ሌላ ጠቃሚ ፋይል ካላችሁ አሁንም ላኩ።",
+  "contrib_reason_new": "\n\n⚠️ ፋይል ለማስገባት ቢያንስ {days} ቀን ቦቱን መጠቀም ያስፈልጋል።",
+  "contrib_reason_blocked": "\n\n⏸ ብዙ ፋይሎች ተቀባይነት ስላላገኙ ለጥቂት ቀን ማስገባት ተዘግቷል።",
+  "contrib_reason_pending": "\n\n⏳ ብዙ ፋይሎች እየተጠበቁ ነው፤ አድሚኑ እስኪያያቸው ጠብቁ።",
+  "contrib_reason_daily": "\n\n📅 ዛሬ የሚፈቀደውን ያህል ልካችኋል፤ ነገ ቀጥሉ።",
+  "contrib_approved": "🎉 ፋይላችሁ ጸድቋል!\n📎 «{title}» → {course}\n+{xp} XP · ለሁሉም ተማሪ ይጠቅማል፣ አመሰግናለሁ! 🙏",
+  "contrib_badge": "🏅 አዲስ ባጅ፦ {badge}!",
+  "contrib_rejected_duplicate": "«{title}» አልተቀበለም፦ ተመሳሳይ ፋይል አስቀድሞ አለ። ሌላ ፋይል ብትልኩ ደስ ይለናል 🙂",
+  "contrib_rejected_quality": "«{title}» አልተቀበለም፦ ጥራቱ (ግልጽነቱ ወይም ይዘቱ) በቂ አይደለም። ግልጽ የሆነ ቅጂ ካላችሁ ላኩ።",
+  "contrib_rejected_notallowed": "«{title}» አልተቀበለም፦ የንግድ መጽሐፍ ወይም ከኮርሱ ጋር የማይገናኝ ይዘት ነው።",
+  "contrib_blocked_notice": "\n⏸ ለጥቂት ቀን አዲስ ፋይል ማስገባት ተዘግቷል።",
+  "badge_bronze": "🥉 አስተዋጽኦ አድራጊ",
+  "badge_silver": "🥈 ብር አስተዋጽኦ አድራጊ",
+  "badge_gold": "🥇 ወርቅ አስተዋጽኦ አድራጊ"
 }

locales/en.json

@@ -37,7 +37,7 @@
   "file_missing": "This file was not found.",
   "search_none": "🔍 Nothing found. Try another word (course name or code).",
   "search_results": "🔍 <b>Results</b> for «{q}»",
-  "profile_text": "👤 <b>{name}</b>\n🎓 {stream} · {year}\n\n🏅 Level {level}: <b>{title}</b>\n⭐ Total XP: <b>{points}</b> ({to_next})\n📅 This week's XP: <b>{week_xp}</b> · {week_rank}\n🔥 Streak: <b>{streak}</b> days (best {best})\n👥 Invited: <b>{refs}</b> (active {refs_q})",
+  "profile_text": "👤 <b>{name}</b>\n🎓 {stream} · {year}\n\n🏅 Level {level}: <b>{title}</b>\n⭐ Total XP: <b>{points}</b> ({to_next})\n📅 This week's XP: <b>{week_xp}</b> · {week_rank}\n🔥 Streak: <b>{streak}</b> days (best {best})\n👥 Invited: <b>{refs}</b> (active {refs_q}){badge}",
   "top_text": "🏆 <b>Weekly ranking</b> · {days} days left\n{rows}\n\n📍 You: <b>{rank}</b> · {week_xp} XP\n⚔️ {n_label}: <b>{natural}</b> · {s_label}: <b>{social}</b>{prize}\n\nℹ️ Rules: /rules",
   "inline_open_bot": "📚 Open the bot",
   "prize_block": "\n\n💰 <b>Weekly prizes</b> (airtime card, birr):\n{lines}\n🎟 Raffle: {raffle} birr (among other eligible players)\nTo qualify: be active {days}+ days this week and earn {xp}+ XP",
@@ -69,5 +69,42 @@
   "group_find_result": "🔍 <b>Found for «{q}»</b>\nTap to open it in the bot 👇",
   "share_btn": "📤 Share with a friend",
   "share_text": "📚 Free study materials for DBU students: slides, past exams, modules, all in one place. Start here 👇",
-  "share_prompt": "👍 Was that useful? Share it with your classmates; you get XP when they join with your link 🎁"
+  "share_prompt": "👍 Was that useful? Share it with your classmates; you get XP when they join with your link 🎁",
+  "btn_contribute": "📤 Contribute a file",
+  "contrib_panel": "📤 <b>Contribute a file</b>\nGot useful material (slides, a module, a past exam, notes)? Send it, it helps every student 🙌\n\n<b>Rules</b>\n• PDF, PPTX or DOCX, up to 20 MB\n• No commercial books or content you are not allowed to share\n• If the file already exists I'll tell you right away\n• It appears in the library only after an admin has checked it\n\n🎁 +{xp} XP when approved (+{bonus} bonus if the course is short of material), up to {cap} files a week\n\n✅ Approved: <b>{approved}</b> · ⏳ Waiting: <b>{pending}</b>{badge}{reason}",
+  "contrib_next_badge": "{n} more file(s) for {badge}",
+  "contrib_btn_go": "📤 Send a file",
+  "contrib_btn_wanted": "🎯 Courses that need files",
+  "contrib_credit_on": "✍️ Credit my name: ✅",
+  "contrib_credit_off": "✍️ Credit my name: ❌",
+  "contrib_credit_saved_on": "OK, your name will appear on approved files",
+  "contrib_credit_saved_off": "OK, your name will not be shown",
+  "contrib_send_now": "OK! Send the file now 📎 (PDF, PPTX or DOCX).\nYou can send several, one by one; this stays open for 10 minutes.",
+  "contrib_send_now_course": "OK! Send a file for <b>{course}</b> 📎 (PDF, PPTX or DOCX).\nThis stays open for 10 minutes.",
+  "contrib_tap_first": "To contribute a file, first tap «📤 Contribute a file» and choose «Send a file» 🙂",
+  "contrib_not_doc": "I only accept PDF, PPTX or DOCX files 🙏",
+  "contrib_too_big": "That file is over 20 MB; please split it in two and send both.",
+  "contrib_dup": "♻️ That file is already in the library: “{title}”. Send another if you have one!",
+  "contrib_accepted": "✅ Got it!\n📎 “{title}”\n📘 {course} · {kind}\n\nOnce an admin approves it, it goes into the library; you'll get +{xp} XP{bonus} 🎁{note}",
+  "contrib_bonus": " (+{n} bonus)",
+  "contrib_near_note": "\n🔍 A similar file exists, so an admin will double-check.",
+  "contrib_need_course": "🤔 Which course is “{title}” for? Pick one 👇",
+  "contrib_course_set": "✅ “{title}” → {course}. I'll tell you when an admin approves it.",
+  "contrib_more_courses": "🔎 Another course",
+  "contrib_change_course": "✏️ Change course",
+  "contrib_wanted": "🎯 <b>These courses need material</b>\nTap one and send a file; you get a bonus 🎁",
+  "contrib_wanted_none": "🎉 Every course has enough material! If you have another useful file, send it anyway.",
+  "contrib_reason_new": "\n\n⚠️ You need to have used the bot for at least {days} days before sending files.",
+  "contrib_reason_blocked": "\n\n⏸ Several files were not accepted, so sending is paused for a few days.",
+  "contrib_reason_pending": "\n\n⏳ Several files are still waiting; please wait until an admin has looked at them.",
+  "contrib_reason_daily": "\n\n📅 You have sent as many as allowed today; continue tomorrow.",
+  "contrib_approved": "🎉 Your file was approved!\n📎 “{title}” → {course}\n+{xp} XP · it helps every student, thank you! 🙏",
+  "contrib_badge": "🏅 New badge: {badge}!",
+  "contrib_rejected_duplicate": "“{title}” was not accepted: a similar file already exists. We'd love another one 🙂",
+  "contrib_rejected_quality": "“{title}” was not accepted: the quality (clarity or content) is not good enough. Send a clearer copy if you have one.",
+  "contrib_rejected_notallowed": "“{title}” was not accepted: it is a commercial book or unrelated to the course.",
+  "contrib_blocked_notice": "\n⏸ Sending new files is paused for a few days.",
+  "badge_bronze": "🥉 Contributor",
+  "badge_silver": "🥈 Silver contributor",
+  "badge_gold": "🥇 Gold contributor"
 }

tests/test_logic.py

@@ -394,6 +394,56 @@ def test_poster_is_a_valid_one_page_pdf():
     assert "@DBUFreshBot" in text and "DBU Freshman Central" in text and "t.me/DBUCentral" in text
 
 
+def test_contribution_rules():
+    from datetime import datetime, timedelta
+
+    from app.services import contrib_rules as K
+
+    assert K.check_file("a.pdf", 1000) is None and K.check_file("A.PPTX", 1000) is None
+    assert K.check_file("a.exe", 1000) == "ext" and K.check_file("a.pdf", K.MAX_BYTES + 1) == "size"
+    assert K.check_file("a.pdf", None) == "size"
+
+    now = datetime(2026, 10, 20, 12, 0)
+    day = lambda n: now - timedelta(days=n)  # noqa: E731
+    assert K.blocked_until([day(1), day(2)], now) is None  # two rejections: still fine
+    assert K.blocked_until([day(1), day(2), day(3)], now) == day(1) + timedelta(days=7)
+    assert K.blocked_until([day(20), day(21), day(22)], now) is None  # too old to count
+    assert K.blocked_until([day(9), day(10), day(11)], now) is None  # block (7 days after day 9) already over
+
+    ok = dict(active_days=3, min_days=2, pending=0, pending_limit=5, today=0, daily_limit=8, blocked=None)
+    assert K.eligibility(**ok) is None
+    assert K.eligibility(**{**ok, "active_days": 1}) == "new"
+    assert K.eligibility(**{**ok, "pending": 5}) == "pending"
+    assert K.eligibility(**{**ok, "today": 8}) == "daily"
+    assert K.eligibility(**{**ok, "blocked": now}) == "blocked"
+
+    assert [K.badge_for(n) for n in (0, 1, 4, 5, 14, 15)] == [None, "bronze", "bronze", "silver", "silver", "gold"]
+    assert K.next_badge(0) == (1, "bronze") and K.next_badge(3) == (2, "silver") and K.next_badge(15) is None
+    assert K.reward(rewarded_this_week=0, course_files_before=0, xp=20, bonus=5, weekly_cap=5) == (20, 5)
+    assert K.reward(rewarded_this_week=0, course_files_before=9, xp=20, bonus=5, weekly_cap=5) == (20, 0)
+    assert K.reward(rewarded_this_week=5, course_files_before=0, xp=20, bonus=5, weekly_cap=5) == (0, 0)
+
+
+def test_qr_png_really_scans():
+    """Decode the PNG with OpenCV's QR reader: proves the code is valid, not just pretty."""
+    try:
+        import cv2
+        import numpy as np
+    except ImportError:
+        return
+    from app.services.qr import qr_png
+
+    link = "https://t.me/DBUFreshBot?start=dorm5"
+    for transparent in (False, True):
+        png = qr_png(link, transparent=transparent)
+        img = cv2.imdecode(np.frombuffer(png, np.uint8), cv2.IMREAD_UNCHANGED)
+        if img.shape[2] == 4:  # transparent: put it on white like a printed page
+            alpha = img[:, :, 3:4] / 255.0
+            img = (img[:, :, :3] * alpha + 255 * (1 - alpha)).astype("uint8")
+        text, _, _ = cv2.QRCodeDetector().detectAndDecode(img)
+        assert text == link, (transparent, text)
+
+
 if __name__ == "__main__":
     for name, fn in list(globals().items()):
         if name.startswith("test_"):