From 6981879f679564348b16b7657d60d6e44e2a78e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= Date: Mon, 29 Jun 2026 11:27:57 +0400 Subject: [PATCH] =?UTF-8?q?docs:=20expanded=20architect=20=E2=80=94=20secu?= =?UTF-8?q?rity,=20prompts=20editor,=20document=20cleanup,=20engineering?= =?UTF-8?q?=20practices,=20testing,=20isolation=20v1.0.184?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- site/templates/architect.html | 208 +++++++++++++++++++++++++++++++--- site/templates/index.html | 2 +- 2 files changed, 196 insertions(+), 14 deletions(-) diff --git a/site/templates/architect.html b/site/templates/architect.html index a44680b..eb680ce 100644 --- a/site/templates/architect.html +++ b/site/templates/architect.html @@ -163,16 +163,70 @@
-

5. Защита и валидация валидация

+

5. Защита от дурака и злонамеренности защита

- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
УгрозаЗащита
ZIP-бомба (архив 1 KB → 10 GB)Лимит 500 файлов, 500 MB, ratio сжатия ≤ 100×
Path traversal в ZIP (../../etc/passwd)Проверка имени файла ДО os.path.basename
Битые кодировки имён в ZIPcp437 → utf8 перекодировка
Файлы не-Word/PDF (exe, картинки, etc.)Whitelist: только pdf/docx/doc/zip — остальные unknown_format
Дубликаты файлов (тот же контент, другое имя)sha256(original_bytes) → пропуск с пометкой duplicate
Дубликаты услуг (одна услуга в разных допниках)UPSERT по name_hash (имя + дата начала) — разные периоды = разные строки
ADD без названия услуги→ UNRESOLVED, не применяется
UPDATE/DELETE без идентификатора целиПустой target_hash → UNRESOLVED
Неизвестный тип операции от LLM→ UNRESOLVED
Кривые числа (1 000,50)Авто-нормализация: пробелы → удалить, запятая → точка
Кривые даты (01.03.2026)Авто-нормализация: DD.MM.YYYY → YYYY-MM-DD
Арифметические ошибкиПроверка price × qty = sum — расхождение → флаг
Мусорные документы (счета, акты, платёжки)Трёхэтапный фильтр: имя файла → заголовки (2000 симв.) → LLM
Тихие ошибки (try/except: pass)Везде logging.warning с контекстом
📋 Заказчик: «кривых документов можно ожидать.
@@ -233,11 +287,139 @@ -

Встроенный редактор с историей версий: сохранил новую версию → она сразу используется LLM. Старые версии остаются в истории — можно откатиться.

+

Встроенный редактор промптов с полным CRUD и историей версий:

+
-

8. Стек технологий

+

8. Хранение документов конфиденциальность

+ +
+📋 Заказчик: «Загрузка из локали, НЕ S3 (конфиденциальность).» +
+ +

Исходные файлы (.docx/.pdf/.doc/zip) НЕ сохраняются в БД. После загрузки и парсинга они удаляются с сервера. В БД хранятся только:

+ +

Сами бинарные файлы на диске не остаются.

+ +
+ +

9. Инженерные практики качество кода

+ +

Decoupling — разделение ответственности

+

Пайплайн разбит на независимые слои с чёткими интерфейсами:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
СлойЧто делаетМожно заменить отдельно
Контракты данных5 frozen dataclass'ов: ParseResult, ClassifyResult, GroupingResult, BatchGroupingResult, CompareOpФормат данных не привязан к хранилищу
LLM-клиентПротокол LLMClient.complete(prompt) → strHttpxLLMClient ↔ FakeLLMClient ↔ другая модель
РепозиторийПротокол Repository (17 методов)PgRepository ↔ MemRepository (тесты)
Загрузкаparse_multipart() — чистая функцияПарсер не зависит от HTTP-фреймворка
Классификацияclassify_batch(batch_id, llm_client, repo) — Dependency InjectionЛюбой LLM + любое хранилище
+ +

Dependency Injection

+

Все внешние зависимости (LLM, БД) пробрасываются через параметры, а не через глобальные import:

+ + +
+ +

10. Тестирование 26/26 PASS

+ + + + + + + + + + + + + + + + + + + + + + +
МодульТестовЧто проверяют
Контракты + загрузка13Создание dataclass'ов, garbage-фильтр, multipart-парсинг, path-traversal
LLM + Репозиторий9FakeLLMClient, MemRepository CRUD, все 17 методов
Классификация4Garbage по имени файла, garbage по заголовкам, classify с FakeLLM, no pending
+ +

Все тесты проходят без доступа к БД и LLM — через FakeLLMClient (record/replay) и MemRepository. Запуск: pytest deploy/tests/ -v.

+ +
+ +

11. Изоляция окружений

+ + + + + + + + + + + + + + + + + + + + +
ОкружениеURLБДНазначение
Продакшенcontracts.kube5s.rucontractsРабочая система
Тестовыйcheck.kube5s.rucontracts_checkОтладка, эксперименты — не затрагивает продакшен
+ +

Тестовое окружение — полная копия пайплайна на отдельном порту (8777) с отдельной БД. Можно загружать, классифицировать, сравнивать — не боясь испортить рабочие данные.

+ +
+ +

12. Стек технологий

@@ -274,7 +456,7 @@
-

9. Конечная цель будущее

+

13. Конечная цель будущее

📋 Заказчик: «Конечная цель: построчное сравнение CRM ↔ фискальная система.
@@ -286,7 +468,7 @@ PAYG (суффикс -m) — особый случай. Сверку с CRM то
-

10. Что дальше требует участия Заказчика

+

14. Что дальше требует участия Заказчика

📋 Заказчик: «Это всё пока опыты и набивание шишек.
diff --git a/site/templates/index.html b/site/templates/index.html index 18ad417..adf5500 100644 --- a/site/templates/index.html +++ b/site/templates/index.html @@ -73,7 +73,7 @@
Nubes - Сверка договоров — LLM AI-driven Event Sourcing v1.0.182-flask + Сверка договоров — LLM AI-driven Event Sourcing v1.0.184-flask
○ Загрузка→ ○ Классификация→