Files
filwordspl-backend/routers/admin_wordsearch.py
Drobysh 80b7f6b419 feat(admin_wordsearch): exclude_maxed_words — не отдавать слова с usage_count >= 5
Слова, использованные в 5+ уровнях, «выгорают» — больше не возвращаются
в конструктор. Админ не может случайно повторно использовать слово.

- get_csv_words: WHERE COALESCE(u.usage_count, 0) < 5
- Хардкод 5 = MAX_USAGE_COUNT (в будущем — в константу)
2026-10-03 17:20:28 +00:00

738 lines
29 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""
Admin Wordsearch Router — конструктор уровней филвордов.
Доступ: только для ADMIN_IDS.
Логика: препод создаёт уровни вручную через админку.
Эндпоинты:
- GET /admin/wordsearch/words?level=A1 — слова из CSV + счётчики
- GET /admin/wordsearch/levels?level=A1 — список созданных уровней
- GET /admin/wordsearch/level/{id} — один уровень (для редактирования)
- POST /admin/wordsearch/level — создать
- PUT /admin/wordsearch/level/{id} — обновить
- DELETE /admin/wordsearch/level/{id} — удалить
- POST /admin/wordsearch/validate — проверить корректность уровня
CRUD слов:
- GET /admin/wordsearch/words/all — полный список слов (с id)
- POST /admin/wordsearch/words — добавить слово
- PUT /admin/wordsearch/words/{word_id} — обновить слово
- DELETE /admin/wordsearch/words/{word_id} — удалить слово
🔧 ОБНОВЛЕНО (30.09.2026): /words/all — пагинация + total.
🔧 ОБНОВЛЕНО (03.10.2026): exclude_maxed_words —
/words не отдаёт слова с usage_count >= 5 (MAX_USAGE_COUNT).
"""
import json
import logging
from typing import Optional
from fastapi import APIRouter, Request, HTTPException
from auth import require_auth
from database import get_pool
from config import ADMIN_IDS
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/admin/wordsearch", tags=["admin-wordsearch"])
LEVELS = ["A1", "A2", "B1", "B2", "C1", "C2"]
MAX_GRID_SIZE = 15
# 🔧 НОВОЕ (03.10.2026): MAX_USAGE_COUNT —
# слово считается «выгоревшим» после 5 использований и не отдаётся
# в конструктор. Хардкод, но легко вынести в конфиг.
MAX_USAGE_COUNT = 5
def _json_or_value(v):
"""🔧 ФИКС (30.09.2026): asyncpg_jsonb_string —
asyncpg возвращает JSONB как строку. Парсим, если строка."""
if isinstance(v, str):
try:
return json.loads(v)
except (json.JSONDecodeError, TypeError):
return v
return v
def _require_admin(telegram_id: int) -> None:
if telegram_id not in ADMIN_IDS:
raise HTTPException(403, "Access denied")
# ============ СЛОВА ИЗ CSV ============
@router.get("/words")
async def get_csv_words(request: Request, level: str = "A1"):
"""
Список слов из CSV для уровня с счётчиком использований.
Сортировка: сначала неиспользованные, потом по алфавиту.
🔧 ОБНОВЛЕНО (03.10.2026): exclude_maxed_words —
слова с usage_count >= MAX_USAGE_COUNT (5) «выгорели» (использованы
слишком много раз). Не отдаём их в конструктор, чтобы админ не мог
использовать повторно.
"""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
if level not in LEVELS:
raise HTTPException(400, f"Invalid level: {level}")
pool = await get_pool()
async with pool.acquire() as conn:
# 🔧 ОБНОВЛЕНО (03.10.2026): exclude_maxed_words —
# слова с usage_count >= 5 «выгорели» (использованы 5 раз).
# Не отдаём их в конструктор, чтобы админ не мог использовать
# повторно. Хардкод 5 = MAX_USAGE_COUNT.
rows = await conn.fetch("""
SELECT
w.word_pl,
w.translation_ru,
w.translation_uk,
w.translation_en,
COALESCE(u.usage_count, 0) AS usage_count
FROM csv_words w
LEFT JOIN word_usage u
ON u.word_pl = w.word_pl AND u.level_code = w.level_code
WHERE w.level_code = $1
AND COALESCE(u.usage_count, 0) < 5
ORDER BY COALESCE(u.usage_count, 0) ASC, w.word_pl ASC
""", level)
return {
"level": level,
"total": len(rows),
"words": [
{
"word_pl": r["word_pl"],
"translation_ru": r["translation_ru"] or "",
"translation_uk": r["translation_uk"] or "",
"translation_en": r["translation_en"] or "",
"usage_count": r["usage_count"],
}
for r in rows
],
}
# ============ УРОВНИ ============
@router.get("/levels")
async def list_levels(request: Request, level: Optional[str] = None):
"""Список созданных вручную уровней филвордов."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
pool = await get_pool()
async with pool.acquire() as conn:
if level and level in LEVELS:
rows = await conn.fetch("""
SELECT id, level_number, grid_size, level, is_active, created_at,
jsonb_array_length(grid_letters) AS rows_count
FROM levels
WHERE created_by IS NOT NULL AND level = $1
ORDER BY level_number ASC, id ASC
""", level)
else:
rows = await conn.fetch("""
SELECT id, level_number, grid_size, level, is_active, created_at,
jsonb_array_length(grid_letters) AS rows_count
FROM levels
WHERE created_by IS NOT NULL
ORDER BY level, level_number ASC, id ASC
""")
return {
"total": len(rows),
"levels": [
{
"id": r["id"],
"level": r["level"],
"level_number": r["level_number"],
"grid_size": r["grid_size"],
"is_active": r["is_active"],
"created_at": r["created_at"].isoformat() if r["created_at"] else None,
}
for r in rows
],
}
@router.get("/level/{level_id}")
async def get_level(request: Request, level_id: int):
"""Один уровень целиком — для редактирования в конструкторе."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
pool = await get_pool()
async with pool.acquire() as conn:
row = await conn.fetchrow("""
SELECT id, level_number, grid_size, level, grid_letters, word_paths,
is_active, created_by, created_at
FROM levels
WHERE id = $1 AND created_by IS NOT NULL
""", level_id)
if not row:
raise HTTPException(404, "Level not found")
# Слова уровня для списка размещённых
words_rows = await conn.fetch("""
SELECT word_pl, translation_ru, translation_uk, translation_en
FROM level_words
WHERE level_id = $1
""", level_id)
return {
"id": row["id"],
"level": row["level"],
"level_number": row["level_number"],
"grid_size": row["grid_size"],
"grid_letters": _json_or_value(row["grid_letters"]),
"word_paths": _json_or_value(row["word_paths"]),
"is_active": row["is_active"],
"created_at": row["created_at"].isoformat() if row["created_at"] else None,
"words": [
{
"word_pl": w["word_pl"],
"translation_ru": w["translation_ru"] or "",
"translation_uk": w["translation_uk"] or "",
"translation_en": w["translation_en"] or "",
}
for w in words_rows
],
}
def _validate_payload(payload: dict) -> tuple[int, list, dict]:
"""
Валидация grid_letters и word_paths.
Returns: (grid_size, grid_letters, word_paths)
Raises: HTTPException(400, ...)
"""
grid_size = payload.get("grid_size")
if not isinstance(grid_size, int) or grid_size < 3 or grid_size > MAX_GRID_SIZE:
raise HTTPException(400, f"grid_size must be 3-{MAX_GRID_SIZE}")
grid_letters = payload.get("grid_letters")
if not isinstance(grid_letters, list) or len(grid_letters) != grid_size:
raise HTTPException(400, "grid_letters must be a 2D array of size grid_size × grid_size")
for row in grid_letters:
if not isinstance(row, list) or len(row) != grid_size:
raise HTTPException(400, "each row of grid_letters must have grid_size elements")
for cell in row:
# Разрешаем: null (неактивная), "", либо одна буква
if cell is not None and (not isinstance(cell, str) or len(cell) > 1):
raise HTTPException(400, "cell must be null, '', or a single character")
word_paths = payload.get("word_paths")
if not isinstance(word_paths, dict):
raise HTTPException(400, "word_paths must be an object")
# Проверяем, что каждое слово в word_paths имеет корректный путь
for word, path in word_paths.items():
if not isinstance(word, str) or not word:
raise HTTPException(400, "word must be a non-empty string")
if not isinstance(path, list) or len(path) == 0:
raise HTTPException(400, f"path for '{word}' must be a non-empty array")
# Проверяем, что путь соседний (Manhattan distance 1)
for i in range(1, len(path)):
prev = path[i - 1]
cur = path[i]
if not (isinstance(prev, list) and len(prev) == 2 and
isinstance(cur, list) and len(cur) == 2):
raise HTTPException(400, f"path points for '{word}' must be [r, c]")
dr = abs(prev[0] - cur[0])
dc = abs(prev[1] - cur[1])
if not (dr <= 1 and dc <= 1 and (dr + dc) > 0):
raise HTTPException(400, f"path for '{word}' has non-adjacent cells")
# Проверяем, что буквы в клетках совпадают со словом
word_upper = word.upper()
if len(path) != len(word_upper):
raise HTTPException(
400,
f"path length for '{word}' ({len(path)}) != word length ({len(word_upper)})"
)
for i, (r, c) in enumerate(path):
if r < 0 or r >= grid_size or c < 0 or c >= grid_size:
raise HTTPException(400, f"path for '{word}' goes out of grid")
cell = grid_letters[r][c]
if cell != word_upper[i]:
raise HTTPException(
400,
f"grid[{r}][{c}] = {cell!r}, expected {word_upper[i]!r} for '{word}'"
)
return grid_size, grid_letters, word_paths
@router.post("/validate")
async def validate_level(request: Request):
"""Проверяет корректность уровня без сохранения."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
body = await request.json()
try:
_validate_payload(body)
except HTTPException as e:
return {"valid": False, "error": e.detail}
return {"valid": True}
# ============ СОЗДАНИЕ / ОБНОВЛЕНИЕ ============
async def _upsert_level_words(conn, level_id: int, level_code: str, word_paths: dict):
"""Обновляет level_words и word_usage для уровня."""
# Получаем переводы из csv_words
words = list(word_paths.keys())
if not words:
return
rows = await conn.fetch("""
SELECT word_pl, translation_ru, translation_uk, translation_en
FROM csv_words
WHERE level_code = $1 AND word_pl = ANY($2::text[])
""", level_code, words)
translations_map = {r["word_pl"]: r for r in rows}
# Удаляем старые level_words
await conn.execute("DELETE FROM level_words WHERE level_id = $1", level_id)
# Вставляем новые
for word in words:
trans = translations_map.get(word, {})
await conn.execute("""
INSERT INTO level_words (level_id, word_pl, translation_ru, translation_uk, translation_en, level)
VALUES ($1, $2, $3, $4, $5, $6)
""", level_id, word,
trans["translation_ru"] if trans else "",
trans["translation_uk"] if trans else "",
trans["translation_en"] if trans else "",
level_code,
)
@router.post("/level")
async def create_level(request: Request):
"""Создать новый уровень."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
body = await request.json()
level_code = body.get("level", "A1")
if level_code not in LEVELS:
raise HTTPException(400, f"Invalid level: {level_code}")
level_number = body.get("level_number")
if not isinstance(level_number, int) or level_number < 1:
raise HTTPException(400, "level_number must be a positive integer")
is_active = bool(body.get("is_active", False))
grid_size, grid_letters, word_paths = _validate_payload(body)
pool = await get_pool()
async with pool.acquire() as conn:
async with conn.transaction():
# 🔧 ФИКС (29.09.2026): проверяем только РУЧНЫЕ уровни.
# Старые авто-сгенерированные (created_by IS NULL) не мешают.
existing = await conn.fetchval("""
SELECT id FROM levels
WHERE level = $1 AND level_number = $2 AND created_by IS NOT NULL
""", level_code, level_number)
if existing:
raise HTTPException(
409,
f"Level {level_code} #{level_number} already exists (id={existing})"
)
# 🔧 ФИКС (30.09.2026): asyncpg_jsonb_str —
# asyncpg требует json.dumps() для JSONB. Без него — DataError.
row = await conn.fetchrow("""
INSERT INTO levels
(level_number, grid_size, game_type, level, grid_letters, word_paths,
is_active, created_by, created_at)
VALUES ($1, $2, 'wordsearch', $3, $4, $5, $6, $7, NOW())
RETURNING id
""",
level_number, grid_size, level_code,
json.dumps(grid_letters), # 🔧 ФИКС (30.09.2026): asyncpg требует str для JSONB
json.dumps(word_paths), # 🔧 ФИКС (30.09.2026): то же
is_active, telegram_id,
)
level_id = row["id"]
# Обновляем level_words
await _upsert_level_words(conn, level_id, level_code, word_paths)
# Обновляем счётчики использований
for word in word_paths.keys():
await conn.execute("""
INSERT INTO word_usage (level_code, word_pl, usage_count, last_used_at)
VALUES ($1, $2, 1, NOW())
ON CONFLICT (level_code, word_pl)
DO UPDATE SET
usage_count = word_usage.usage_count + 1,
last_used_at = NOW()
""", level_code, word)
logger.info(
f"[admin_wordsearch] level created: {level_code} #{level_number} "
f"(id={level_id}, {len(word_paths)} words, active={is_active}) "
f"by admin {telegram_id}"
)
return {"status": "ok", "level_id": level_id}
@router.put("/level/{level_id}")
async def update_level(request: Request, level_id: int):
"""Обновить уровень."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
body = await request.json()
pool = await get_pool()
async with pool.acquire() as conn:
existing = await conn.fetchrow("""
SELECT id, level, level_number, word_paths FROM levels
WHERE id = $1 AND created_by IS NOT NULL
""", level_id)
if not existing:
raise HTTPException(404, "Level not found")
level_code = existing["level"]
# 🔧 ФИКС (30.09.2026): usage_count_reflects_current —
# читаем старые слова, чтобы откатить их счётчики при замене.
old_word_paths_raw = existing["word_paths"]
old_word_paths = json.loads(old_word_paths_raw) if isinstance(old_word_paths_raw, str) else old_word_paths_raw
old_words = set(old_word_paths.keys())
grid_size, grid_letters, word_paths = _validate_payload(body)
is_active = bool(body.get("is_active", False))
async with conn.transaction():
# 🔧 ФИКС (30.09.2026): asyncpg_jsonb_str —
# asyncpg требует json.dumps() для JSONB. Без него — DataError.
await conn.execute("""
UPDATE levels
SET grid_size = $1,
grid_letters = $2,
word_paths = $3,
is_active = $4
WHERE id = $5
""",
grid_size,
json.dumps(grid_letters), # 🔧 ФИКС (30.09.2026): asyncpg требует str для JSONB
json.dumps(word_paths), # 🔧 ФИКС (30.09.2026): то же
is_active,
level_id,
)
await _upsert_level_words(conn, level_id, level_code, word_paths)
# 🔧 ФИКС (30.09.2026): usage_count_reflects_current —
# 1) Откатываем счётчики для слов, которых НЕТ в новом уровне.
# 2) Добавляем/инкрементим для новых слов.
# 3) Пересечение — не трогаем (last_used_at обновляем).
new_words = set(word_paths.keys())
words_added = new_words - old_words # новые слова
words_removed = old_words - new_words # убранные слова
# Откатываем счётчики для убранных
for word in words_removed:
await conn.execute("""
UPDATE word_usage
SET usage_count = GREATEST(0, usage_count - 1)
WHERE level_code = $1 AND word_pl = $2
""", level_code, word)
# Если счётчик = 0 — удаляем строку (чтобы не мусорить)
await conn.execute("""
DELETE FROM word_usage
WHERE level_code = $1 AND word_pl = $2 AND usage_count <= 0
""", level_code, word)
# Инкрементим для новых
for word in words_added:
await conn.execute("""
INSERT INTO word_usage (level_code, word_pl, usage_count, last_used_at)
VALUES ($1, $2, 1, NOW())
ON CONFLICT (level_code, word_pl)
DO UPDATE SET
usage_count = word_usage.usage_count + 1,
last_used_at = NOW()
""", level_code, word)
# Для пересечения — обновляем только last_used_at
for word in new_words & old_words:
await conn.execute("""
UPDATE word_usage
SET last_used_at = NOW()
WHERE level_code = $1 AND word_pl = $2
""", level_code, word)
logger.info(
f"[admin_wordsearch] level updated: id={level_id} "
f"({len(word_paths)} words, active={is_active}) "
f"by admin {telegram_id}"
)
return {"status": "ok", "level_id": level_id}
@router.delete("/level/{level_id}")
async def delete_level(request: Request, level_id: int):
"""Удалить уровень (только созданные вручную)."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
pool = await get_pool()
async with pool.acquire() as conn:
row = await conn.fetchrow("""
SELECT id, level, level_number FROM levels
WHERE id = $1 AND created_by IS NOT NULL
""", level_id)
if not row:
raise HTTPException(404, "Level not found")
await conn.execute("DELETE FROM levels WHERE id = $1", level_id)
logger.info(
f"[admin_wordsearch] level deleted: id={level_id} "
f"({row['level']} #{row['level_number']}) by admin {telegram_id}"
)
return {"status": "ok", "level_id": level_id}
# ============ CRUD СЛОВ (csv_words) ============
@router.post("/words")
async def create_csv_word(request: Request):
"""Добавить слово в csv_words."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
body = await request.json()
level_code = (body.get("level_code") or "").strip()
word_pl = (body.get("word_pl") or "").strip().lower()
translation_ru = (body.get("translation_ru") or "").strip()
translation_uk = (body.get("translation_uk") or "").strip()
translation_en = (body.get("translation_en") or "").strip()
if level_code not in LEVELS:
raise HTTPException(400, f"Invalid level: {level_code}")
if not word_pl:
raise HTTPException(400, "word_pl is required")
# 🔧 ФИКС (30.09.2026): global_duplicate_warning —
# проверяем все уровни. Если есть — возвращаем 409 с уровнем.
# Фронт покажет предупреждение + кнопку "Всё равно добавить".
# С флагом `force=true` — пропускаем проверку.
force = bool(body.get("force", False))
pool = await get_pool()
async with pool.acquire() as conn:
if not force:
existing = await conn.fetchrow("""
SELECT id, level_code FROM csv_words
WHERE LOWER(word_pl) = LOWER($1)
ORDER BY
CASE level_code
WHEN 'A1' THEN 1 WHEN 'A2' THEN 2
WHEN 'B1' THEN 3 WHEN 'B2' THEN 4
WHEN 'C1' THEN 5 WHEN 'C2' THEN 6
ELSE 7
END
LIMIT 1
""", word_pl)
if existing:
existing_level = existing["level_code"]
if existing_level == level_code:
raise HTTPException(
409,
f"DUPLICATE_SAME_LEVEL|{word_pl}|{existing_level}"
)
else:
raise HTTPException(
409,
f"DUPLICATE_OTHER_LEVEL|{word_pl}|{existing_level}"
)
row = await conn.fetchrow("""
INSERT INTO csv_words (level_code, word_pl, translation_ru, translation_uk, translation_en)
VALUES ($1, $2, $3, $4, $5)
RETURNING id
""", level_code, word_pl, translation_ru, translation_uk, translation_en)
logger.info(f"[admin_wordsearch] csv_word created: #{row['id']} '{word_pl}' in {level_code} by admin {telegram_id}")
return {"status": "ok", "word_id": row["id"]}
@router.put("/words/{word_id}")
async def update_csv_word(request: Request, word_id: int):
"""Обновить слово в csv_words."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
body = await request.json()
word_pl = (body.get("word_pl") or "").strip().lower()
translation_ru = (body.get("translation_ru") or "").strip()
translation_uk = (body.get("translation_uk") or "").strip()
translation_en = (body.get("translation_en") or "").strip()
if not word_pl:
raise HTTPException(400, "word_pl is required")
pool = await get_pool()
async with pool.acquire() as conn:
existing = await conn.fetchrow("SELECT level_code, word_pl FROM csv_words WHERE id = $1", word_id)
if not existing:
raise HTTPException(404, "Word not found")
await conn.execute("""
UPDATE csv_words
SET word_pl = $1,
translation_ru = $2,
translation_uk = $3,
translation_en = $4
WHERE id = $5
""", word_pl, translation_ru, translation_uk, translation_en, word_id)
# 🔧 Синхронизируем с level_words (для филвордов)
await conn.execute("""
UPDATE level_words
SET word_pl = $1, translation_ru = $2, translation_uk = $3, translation_en = $4
WHERE word_pl = $5
""", word_pl, translation_ru, translation_uk, translation_en, existing["word_pl"])
logger.info(f"[admin_wordsearch] csv_word updated: #{word_id} '{existing['word_pl']}' -> '{word_pl}' by admin {telegram_id}")
return {"status": "ok", "word_id": word_id}
@router.delete("/words/{word_id}")
async def delete_csv_word(request: Request, word_id: int):
"""Удалить слово из csv_words."""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
pool = await get_pool()
async with pool.acquire() as conn:
existing = await conn.fetchrow("SELECT level_code, word_pl FROM csv_words WHERE id = $1", word_id)
if not existing:
raise HTTPException(404, "Word not found")
await conn.execute("DELETE FROM csv_words WHERE id = $1", word_id)
logger.info(f"[admin_wordsearch] csv_word deleted: #{word_id} '{existing['word_pl']}' by admin {telegram_id}")
return {"status": "ok", "word_id": word_id}
@router.get("/words/all")
async def list_all_csv_words(
request: Request,
level: Optional[str] = None,
q: Optional[str] = None,
page: int = 1,
limit: int = 50,
):
"""
🔧 ОБНОВЛЕНО (30.09.2026): пагинация + total.
Возвращает:
{
"total": 2446, # всего под фильтром
"page": 1, # текущая страница
"limit": 50, # размер страницы
"pages": 49, # всего страниц
"words": [...], # слова текущей страницы
}
"""
telegram_id, _ = await require_auth(request)
_require_admin(telegram_id)
if page < 1:
page = 1
if limit < 1:
limit = 1
elif limit > 500:
limit = 500
offset = (page - 1) * limit
pool = await get_pool()
async with pool.acquire() as conn:
# Условия
conditions = []
params: list = []
idx = 1
if level and level in LEVELS:
conditions.append(f"level_code = ${idx}")
params.append(level)
idx += 1
if q and q.strip():
conditions.append(f"""(
word_pl ILIKE ${idx} OR
translation_ru ILIKE ${idx} OR
translation_uk ILIKE ${idx} OR
translation_en ILIKE ${idx}
)""")
params.append(f"%{q.strip()}%")
idx += 1
where = ("WHERE " + " AND ".join(conditions)) if conditions else ""
# Общее количество
total = await conn.fetchval(f"""
SELECT COUNT(*) FROM csv_words {where}
""", *params) or 0
# Страница
rows = await conn.fetch(f"""
SELECT id, level_code, word_pl, translation_ru, translation_uk, translation_en
FROM csv_words
{where}
ORDER BY level_code, word_pl
LIMIT ${idx} OFFSET ${idx + 1}
""", *params, limit, offset)
pages = (total + limit - 1) // limit if limit > 0 else 1
return {
"total": total,
"page": page,
"limit": limit,
"pages": pages,
"words": [
{
"id": r["id"],
"level_code": r["level_code"],
"word_pl": r["word_pl"],
"translation_ru": r["translation_ru"] or "",
"translation_uk": r["translation_uk"] or "",
"translation_en": r["translation_en"] or "",
}
for r in rows
],
}