diff --git a/README.md b/README.md
index b5ec8c2..1be5b54 100644
--- a/README.md
+++ b/README.md
@@ -10,18 +10,21 @@ Telegram-бот — только часть рабочего окружения
## Текущее состояние
Сейчас реализованы Telegram-бот-секретарь версии `0.2.2`, backend версии
-`0.13.2` и frontend `0.3.3` с поисковым экраном, внутренней лабораторией и
+`0.13.4` и frontend `0.3.4` с поисковым экраном, внутренней лабораторией и
согласованным отображением доступных действий учетной записи.
Авторизация хранится в
SQLite; первый пользователь `admin` создаётся интерактивной CLI-командой.
-Поиск расширяет аббревиатуры организационно-правовых форм и поднимает
-действующий Налоговый кодекс для запросов о налоге на прибыль.
+Поиск расширяет аббревиатуры организационно-правовых форм, применяет узкий
+юридический вариант для общего словосочетания «договор аренды» и поднимает
+действующий Налоговый кодекс для запросов о налоге на прибыль. Ограничения
+текущего индекса и подтверждённые тестовые ошибки описаны в
+[отчёте о релевантности](docs/product/search-relevance-findings-2026-11-03.md).
| Компонент | Версия | Состояние |
|---|---:|---|
| Telegram-бот | `0.2.2` | на Synology работает `0.2.1`; обновление после слияния |
-| Backend | `0.13.2` | авторизация, серверная capability управления пользователями, поиск и статические ресурсы |
-| Frontend | `0.3.3` | поиск по правовой базе, просмотр редакций, внутренняя лаборатория и контекстная навигация кабинета |
+| Backend | `0.13.4` | авторизация, серверная capability управления пользователями, поиск и статические ресурсы |
+| Frontend | `0.3.4` | поиск по правовой базе, просмотр редакций, внутренняя лаборатория и контекстная навигация кабинета |
| Сбор и обработка правовых данных | `0.8.0` | добавлены relevance set и оценка выдачи |
| RAG и база знаний | — | ещё не созданы |
@@ -64,4 +67,4 @@ python3 -m unittest discover -s tools/telegram-bot -v
---
-Акылдаш · Telegram-бот v0.2.2 · Backend v0.13.2 · Frontend v0.3.3
+Акылдаш · Telegram-бот v0.2.2 · Backend v0.13.4 · Frontend v0.3.4
diff --git a/backend/README.md b/backend/README.md
index d7e7e88..04ee2d3 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -274,6 +274,9 @@ PYTHONPATH=backend python3 -m search.evaluate_relevance \
Менять веса или анализаторы следует только после фиксации этого baseline и
разбора ошибок выдачи.
+Диагностический отчёт с измерениями, подтверждёнными ошибками и ограничениями
+текущего корпуса: [search relevance findings](../docs/product/search-relevance-findings-2026-11-03.md).
+
## Внутренняя лаборатория релевантности
Создайте первую учетную запись администратора:
@@ -292,7 +295,8 @@ PYTHONPATH=backend python3 -m search.api \\
Лаборатория показывает фактический порядок выдачи OpenSearch, позволяет открыть
текст редакции, поставить результату оценку от 0 до 3 и сохранить снимок с
-комментариями. Поиск и API доступны только после входа. Пользователь `admin`
+комментариями. Пустую выдачу можно сохранить как query-level оценку с
+обязательным общим комментарием. Поиск и API доступны только после входа. Пользователь `admin`
управляет учетными записями; новые пользователи должны заменить временный
пароль при первом входе. Хранилище пользователей `data/search-users.sqlite3`
нужно резервировать отдельно от поискового индекса. Экспорт доступен
diff --git a/backend/search/api.py b/backend/search/api.py
index d69fe59..b8207ae 100644
--- a/backend/search/api.py
+++ b/backend/search/api.py
@@ -21,7 +21,7 @@ from search.reviews import ReviewSnapshots, ReviewStore
API_VERSION = "v1"
-SEARCH_ALGORITHM_VERSION = "search-6"
+SEARCH_ALGORITHM_VERSION = "search-7"
LANGUAGES = {"ru", "ky"}
CODE = re.compile(r"^[0-9]+$")
MAX_PAGE_SIZE = 100
@@ -286,6 +286,8 @@ class Api:
by_rank = {item["rank"]: item for item in snapshot["results"]}
if len(submitted) != len(by_rank) or {item.get("rank") for item in submitted if isinstance(item, dict)} != set(by_rank):
raise ApiError(400, "all search results must be reviewed exactly once")
+ if not snapshot["results"] and not overall_comment.strip():
+ raise ApiError(400, "overall_comment is required for an empty search result")
results = []
for item in submitted:
if not isinstance(item, dict) or not isinstance(item.get("rank"), int) or item["rank"] not in by_rank:
@@ -300,8 +302,6 @@ class Api:
if not isinstance(comment, str) or len(comment) > 4000:
raise ApiError(400, "result comment is too long")
results.append({**source, "rating": rating, "comment": comment.strip()})
- if not results:
- raise ApiError(400, "at least one result must be reviewed")
review = {"created_at": datetime.datetime.now(datetime.timezone.utc).isoformat(), "reviewer": reviewer, "query": snapshot["query"], "language": snapshot["language"], "index_name": snapshot["index_name"], "algorithm_version": snapshot["algorithm_version"], "top_result_code": snapshot["results"][0]["code"] if snapshot["results"] else None, "results": results, "overall_comment": overall_comment}
review_id = self.review_store.save(review)
return {"api_version": API_VERSION, "id": review_id, "created_at": review["created_at"]}
diff --git a/backend/search/evaluate_relevance.py b/backend/search/evaluate_relevance.py
index e5b2eb8..bd5e48e 100644
--- a/backend/search/evaluate_relevance.py
+++ b/backend/search/evaluate_relevance.py
@@ -82,7 +82,7 @@ def main() -> int:
raise SystemExit("--top-k must be greater than zero")
result = evaluate(load_queries(arguments.relevance_set), arguments.url, arguments.index, arguments.top_k)
print(json.dumps(result, ensure_ascii=False, indent=2))
- print(f"Akyldash · Backend v{APP_VERSION} · Frontend v0.1.2", file=sys.stderr)
+ print(f"Akyldash · Backend v{APP_VERSION} · Frontend v0.3.4", file=sys.stderr)
return 0
diff --git a/backend/search/minjust_opensearch.py b/backend/search/minjust_opensearch.py
index 0e67b8d..f7167af 100644
--- a/backend/search/minjust_opensearch.py
+++ b/backend/search/minjust_opensearch.py
@@ -17,7 +17,7 @@ from typing import Iterator
from search.catalog import authority_codes, legal_force_code, source_code
-APP_VERSION = "0.13.3"
+APP_VERSION = "0.13.4"
LANGUAGES = {"ru", "ky"}
DEFAULT_MAPPING = Path(__file__).with_name("minjust-fragments-index.json")
@@ -552,7 +552,7 @@ def main() -> int:
else:
documents, fragments = export_bulk(arguments.input, arguments.output, arguments.index, arguments.limit)
destination = arguments.output
- print(f"documents={documents} fragments={fragments} destination={destination}\nAkyldash · Backend v{APP_VERSION} · Frontend v0.3.3")
+ print(f"documents={documents} fragments={fragments} destination={destination}\nAkyldash · Backend v{APP_VERSION} · Frontend v0.3.4")
return 0
diff --git a/backend/search/query.py b/backend/search/query.py
index aca26af..0e9e75f 100644
--- a/backend/search/query.py
+++ b/backend/search/query.py
@@ -22,6 +22,18 @@ LEGAL_FORM_ALIASES = {
"жоопкерчилиги чектелген коом": ("жчк",),
},
}
+# The indexed Civil Code uses the legal term "имущественный наем" for a
+# договор аренды. Keep this exact legal phrase expansion narrow: it must not
+# rewrite residential hiring, employment, sublease, or leasing queries.
+LEASE_TERM_ALIAS = re.compile(
+ r"(? list[str]:
pattern = re.compile(rf"(? int:
if arguments.top_k <= 0:
raise SystemExit("--top-k must be greater than zero")
print(json.dumps(search_documents(arguments.url, arguments.index, arguments.language, arguments.query, arguments.top_k), ensure_ascii=False))
- print(f"Akyldash · Backend v{APP_VERSION} · Frontend v0.1.2")
+ print(f"Akyldash · Backend v{APP_VERSION} · Frontend v0.3.4")
return 0
diff --git a/backend/search/review.html b/backend/search/review.html
index d38c2c4..89547af 100644
--- a/backend/search/review.html
+++ b/backend/search/review.html
@@ -657,7 +657,7 @@
@@ -675,7 +675,7 @@
-
+
diff --git a/backend/test_search_relevance.py b/backend/test_search_relevance.py
index 510efc0..db26506 100644
--- a/backend/test_search_relevance.py
+++ b/backend/test_search_relevance.py
@@ -49,6 +49,31 @@ class SearchRelevanceTest(unittest.TestCase):
self.assertIn("регистрация осоо", [variant.casefold() for variant in query_variants("ru", "регистрация общества с ограниченной ответственностью")])
self.assertIn("жчк ачуу тартиби", [variant.casefold() for variant in query_variants("ky", "жоопкерчилиги чектелген коом ачуу тартиби")])
+ def test_russian_lease_phrase_expands_only_the_exact_legal_construction(self):
+ original = "расторжение договора аренды"
+ variants = query_variants("ru", original)
+ self.assertEqual(variants[0], original)
+ self.assertIn("расторжение договора имущественного найма", variants)
+ body = json.loads(build_search_body("ru", original, 10))
+ clauses = body["query"]["bool"]["must"]["bool"]["should"]
+ full_text = [item["multi_match"]["query"] for item in clauses if "multi_match" in item and item["multi_match"].get("operator") == "AND"]
+ self.assertEqual(full_text, variants)
+
+ for query in (
+ "аренда квартиры",
+ "расторжение договора аренды квартиры",
+ "договор аренды земельного участка",
+ "договор поднайма",
+ "наем работника",
+ "договор лизинга",
+ ):
+ self.assertEqual(query_variants("ru", query), [query])
+
+ self.assertEqual(
+ query_variants("ru", "договору аренды"),
+ ["договору аренды", "договору имущественного найма"],
+ )
+
def test_relaxed_match_drops_ru_template_prefix_and_stays_low_weight(self):
body = json.loads(build_search_body("ru", "правовое регулирование расторжение договора аренды", 10))
clauses = body["query"]["bool"]["must"]["bool"]["should"]
diff --git a/backend/test_search_reviews.py b/backend/test_search_reviews.py
index 06f8e9d..be7ef68 100644
--- a/backend/test_search_reviews.py
+++ b/backend/test_search_reviews.py
@@ -13,6 +13,8 @@ class SearchReviewTest(unittest.TestCase):
response = {"hits": {"hits": [{"_index": "search-20260827", "_source": {"document_code": "7", "edition_code": "10", "document_name_ru": "Закон"}}, {"_index": "search-20260827", "_source": {"document_code": "8", "edition_code": "11", "document_name_ru": "Кодекс"}}]}}
with patch("search.api.request_json", return_value=response):
result = api.handle("GET", "/search?q=test&language=ru&page_size=2")[1]
+ with self.assertRaisesRegex(ApiError, "exactly once"):
+ api.handle("POST", "/search-reviews", {"review_token": result["review_token"], "reviewer": "Юрист", "results": []})
with self.assertRaisesRegex(ApiError, "exactly once"):
api.handle("POST", "/search-reviews", {"review_token": result["review_token"], "reviewer": "Юрист", "results": [{"rank": 1, "code": "7", "rating": 3}]})
@@ -30,6 +32,34 @@ class SearchReviewTest(unittest.TestCase):
with self.assertRaisesRegex(ApiError, "does not match"):
api.handle("POST", "/search-reviews", {"review_token": result["review_token"], "reviewer": "Юрист", "results": [{"rank": 1, "code": "8", "rating": 3}]})
+ def test_saves_signed_empty_snapshot_with_query_level_comment(self):
+ with tempfile.TemporaryDirectory() as temporary:
+ api = Api("http://opensearch:9200", "current", Path(temporary), Path(temporary) / "reviews.sqlite3", b"test-secret")
+ with patch("search.api.request_json", return_value={"hits": {"hits": []}}):
+ result = api.handle("GET", "/search?q=редкий+запрос&language=ru")[1]
+ body = {
+ "review_token": result["review_token"],
+ "reviewer": "Юрист",
+ "overall_comment": "Пустая выдача подтверждена.",
+ "results": [],
+ }
+ with self.assertRaisesRegex(ApiError, "overall_comment is required"):
+ api.handle("POST", "/search-reviews", {**body, "overall_comment": ""})
+ saved = api.handle("POST", "/search-reviews", body)
+ self.assertEqual(saved[0], 201)
+ review = api.handle("GET", "/search-reviews/export")[1]["reviews"][0]
+ self.assertIsNone(review["top_result_code"])
+ self.assertEqual(review["results"], [])
+ self.assertEqual(review["overall_comment"], body["overall_comment"])
+
+ def test_review_page_enables_query_level_review_for_empty_results(self):
+ with tempfile.TemporaryDirectory() as temporary:
+ api = Api("http://opensearch:9200", "current", Path(temporary))
+ page = api.review_page()
+ self.assertIn("state.results.length ? 'Сохранить оценку' : 'Сохранить пустую выдачу'", page)
+ self.assertIn("aria-required', String(!state.results.length)", page)
+ self.assertIn("const results = state.results.map((result, index) => { const item", page)
+
def test_snapshot_and_review_page_are_available(self):
with tempfile.TemporaryDirectory() as temporary:
api = Api("http://opensearch:9200", "current", Path(temporary))
diff --git a/docs/product/search-relevance-findings-2026-11-03.md b/docs/product/search-relevance-findings-2026-11-03.md
new file mode 100644
index 0000000..263958c
--- /dev/null
+++ b/docs/product/search-relevance-findings-2026-11-03.md
@@ -0,0 +1,142 @@
+# Диагностика релевантности поиска — 3 ноября 2026 года
+
+## Решения и границы
+
+Эта заметка фиксирует исходные измерения от 2 ноября, узкое исправление
+терминологии и контракт для закрытия пробела корпуса. Она не утверждает, что
+поиск уже стал юридически релевантнее: новая выдача должна быть проверена
+отдельно на изолированном стенде и сравнена с исходными снимками. Полный набор
+из 7 500 запросов повторно не собирался.
+
+Изменён backend `0.13.3` → `0.13.4`, frontend внутренней лаборатории
+`0.3.3` → `0.3.4`, версия алгоритма `search-6` → `search-7`.
+
+## Исходный benchmark
+
+Зафиксированный набор содержит 7 500 русских формулировок: 15 тематических
+групп, по 500 запросов в каждой. Это 750 тем с десятью вариантами формулировки,
+а не 7 500 независимых правовых ситуаций. Исходный индекс
+`akyldash-fragments-v2` содержал около 42,6 млн фрагментов и занимал 11,2 ГБ.
+
+| Показатель Акылдаш, исходный прогон | Результат |
+|---|---:|
+| Собранные выдачи | 7 500 / 7 500 |
+| Пустые выдачи | 6 |
+| Медиана / P95 ответа | 21,67 / 77,36 мс |
+| Совпадение основ темы в видимых названии/фрагменте, top 1 | 40,57% |
+| То же, top 3 / top 10 | 47,05% / 51,40% |
+
+Сравнение с КонсультантПлюс в исходном отчёте — только диагностическое:
+юрисдикции и корпуса различаются. Совпадение основ темы не измеряет Recall,
+MRR, полноту ответа или юридическую правильность; российская выдача не является
+эталоном права Кыргызстана. Для вывода о качестве нужны экспертные релевантные
+коды, контрольный набор и отдельные метрики.
+
+## Подтверждённые классы ошибок
+
+14 коротких документов прочитаны целиком; по ним сохранено 79 оценок пар
+«запрос—документ» в 71 сессии: 59 нерелевантных и 20 косвенно полезных.
+Неоценённые результаты не считались ошибками.
+
+| Тема | Наблюдавшийся неверный приоритет | Вывод |
+|---|---:|---|
+| Расторжение договора аренды | 135066 | Решение по одной сделке с землёй не даёт общих оснований расторжения |
+| Международный коммерческий арбитраж | 26411 | Продажа земельных участков не регулирует арбитраж и отказ в признании решения |
+| Испытательный срок работника | 94603 | Земельный участок под завод/испытательный полигон совпадает словами, но не предметом |
+| Место жительства ребёнка | 50760 | Финансирование приюта не устанавливает порядок спора родителей |
+| Перевод студента в другой вуз | 14165 | Разовое финансирование студентов не устанавливает процедуру перевода |
+| Таможенные пошлины | 41854 | Индивидуальная отсрочка одному предприятию не задаёт общие правила |
+| Общий порядок предоставления земли | 54735, 54571 | Решения по отдельным участкам не являются общей процедурой |
+| Защита критической инфраструктуры | 59082 | Предоставление земли под завод не устанавливает защитные требования |
+| Купля-продажа / расторжение договора | 60053 | Расторжение одной сделки с госакциями не является общей нормой |
+| Подача искового заявления | 18516, 7115 | Отдельный спор и узкая льгота по пошлине не дают общего порядка подачи иска |
+| Принятие нормативных актов | 77190 | Первое чтение одного законопроекта не устанавливает общий процесс |
+| Подключение к водоснабжению | 135061 | Целевая помощь отдельным домохозяйствам не задаёт технические условия |
+
+Проверенные варианты глобального повышения веса кодексов отвергнуты: вес 2 не
+исправил аренду и подачу иска, а вес 4 поднял Налоговый кодекс выше профильных
+источников по воинской обязанности и подаче иска. Общие веса или жёсткие
+приоритеты кодексов не добавлялись.
+
+## Узкая терминологическая поправка
+
+В исследованной редакции ГК КР II (код 5, редакция 460) глава 27 и статья 542
+связывают договор аренды с имущественным наймом; статьи 558–559 используют
+термин «имущественный наем». В полном тексте этой редакции буквальная фраза
+«расторжение договора аренды» не встречалась. Исходный запрос возвращал код
+135066 на первом месте, а формулировка «расторжение договора имущественного
+найма» — код 5.
+
+Backend теперь сохраняет исходную строку и добавляет только для точного
+сочетания «договор [арендная форма]» вариант «договор [та же форма]
+имущественного найма». В частности, `договора аренды` превращается в
+`договора имущественного найма`. Расширение не срабатывает для аренды квартиры
+или земельного участка, поднайма, найма работника или лизинга. Точный запрос остаётся в строгой
+лексической ветке, поэтому его профильный муниципальный акт не выкидывается из
+поиска. Фактический top-k после изменения и влияние на соседние запросы требуют
+отдельного A/B прогона; кодовый тест проверяет только варианты и DSL.
+
+## Пустые выдачи в лаборатории
+
+Исходный контракт блокировал сохранение шести подписанных пустых снимков:
+API отвергал `results: []`, а интерфейс читал поля из пустого placeholder.
+Теперь signed snapshot может сохранить пустую оценку с обязательным общим
+комментарием. В записи `top_result_code` остаётся `null`, список результатов
+пустой. Непустой снимок по-прежнему обязан получить оценку каждого ранга ровно
+один раз, совпадающую с подписанным кодом документа. HMAC, TTL и текущая
+аутентификация не меняются.
+
+Существующая отдельная база локальной лаборатории содержала 7 494 сохранённых
+сессии, 79 экспертных оценок и 55 516 диагностических комментариев; 74 715
+оценок результатов остались пустыми намеренно. Integrity check прошёл,
+порядок кодов и редакций baseline не менялся. Эти сохранённые оценки не
+переписывались; шесть пустых сессий должны быть размечены отдельно после
+выпуска интерфейса.
+
+## Пробел актуального корпуса и безопасный контракт закрытия
+
+Отдельно от ранжирования, в проверенном тестовом индексе не было трёх
+подтверждённых действующих актов (все три canonical ID имели `_count = 0`):
+
+| Акт | Canonical ID | Последняя проверенная редакция |
+|---|---:|---|
+| Трудовой кодекс КР от 23.01.2025 № 23 | 230021083 | 57548 от 28.07.2026 |
+| Земельный кодекс КР от 18.07.2025 № 149 | 230029465 | 34746 от 18.07.2025 |
+| Об охране здоровья граждан КР от 12.01.2024 № 14 | 230000918 | 47553 от 23.01.2026 |
+
+В индексе присутствуют прежние отменённые трудовой и земельный кодексы; нельзя
+переименовать или поднять их как замену отсутствующим актуальным нормам.
+Подготовленные для отдельной проверки точные RU/KY тексты — 3 документа и
+8 934 фрагмента — пока не составляют полного корпуса и не подключены к
+работающему индексу. Вложения и история редакций отдельно не подтверждены.
+
+Закрытие пробела требует отдельного контролируемого обновления данных:
+
+1. Заново сверить официальные canonical ID, статус, edition ID и дату; сохранить
+ исходный ответ, хеши и provenance в отдельном staging-каталоге.
+2. Проверить полноту обеих языковых версий, ссылки на редакции, историю и
+ вложения; не импортировать метаданные с ненужными персональными полями.
+3. Нормализовать отдельно от текущего корпуса и проверить counts/хеши; затем
+ пересобрать полный версионный индекс из базового корпуса и дополнений.
+4. На изолированном стенде проверить наличие актуальных canonical ID, открытие
+ документа/редакции через API, активность статуса, RU/KY поиск и контрольные
+ запросы к прежним источникам. Не применять поправку как прямую запись в
+ действующий индекс и не переключать alias до полного сравнения.
+5. Публикация требует отдельного владельческого разрешения и проверенного
+ rollback. Эта PR не загружает документы, не меняет индекс или production.
+
+## Что остаётся проверить
+
+- Root-owned изолированный прогон на 8081 должен проверить реальный top-k новой
+ терминологической ветки и регрессии на контрольных примерах.
+- Полный benchmark после изменения нужен для нового snapshot и сравнения; он
+ выполняется отдельно от исходной сбора 7 500 выдач.
+- Актуальные три акта требуют отдельной проверки полноты/лицензии/истории и
+ контролируемой полной пересборки корпуса. Их отсутствие не решается
+ ранжированием.
+- Независимое ревью и CI этой PR не заменяют экспертную оценку правового ответа.
+
+Исходные измерения и хеши хранятся вне репозитория в рабочем наборе
+`search-benchmark-2026-11-02`. В этот репозиторий не включаются сырые ответы
+MinJust, диагностические логи, внешние пользовательские данные или выгрузка
+лабораторных комментариев.