docs: код-ревью ассистента + правки (поиск *_sub_user, per-call таймаут) в HISTORY и ASSISTANT_ARCHITECTURE

HISTORY/2026-10-12_code_review_and_fixes.md

@@ -0,0 +1,73 @@
+# tf_docs: код-ревью AI-ассистента и правки (поиск подресурсов + таймаут ЛЛМ)
+
+Дата: 2026-10-12
+Коммит: `12d29ee` (репозиторий `tf_docs`, ветка `master`, запушен)
+Контекст: по запросу — фактическое ревью кода/архитектуры ассистента с упором на ЛЛМ.
+
+## Что проверялось
+
+Прочитан backend целиком: `server.js`, `assist.js`, `search.js`, `stage1.js`,
+`stage2.js`, `orchestrator.js`; сверено с `llm_project/docs/ASSISTANT_ARCHITECTURE.md`
+и результатами прогонов (`llm_project/tests/RESULTS_*.json`).
+
+## Найдено (факты, `файл:строка` на момент ревью)
+
+1. **🔴 `search.js:206-215`** — `resourceBaseSegment` перебирал суффиксы-подресурсы
+   в исходном порядке, где `_user` стоит раньше `_sub_user`. Для
+   `nubes_s3_sub_user` (rest=`s3_sub_user`) отрезался `_user` → base `s3_sub`
+   вместо `s3`. Следствие: `isResourcePage` не находила страницу ресурса
+   (`"s3_sub_user" !== "s3"`), поиск по `resource_type` для `*_sub_user` был
+   неэффективен. Реальный ресурс (есть в `golden_questions_300.json`); эффект
+   маскировался лексическим поиском по исходному вопросу.
+2. **🔴 `assist.js:25`** — `ASSIST_LLM_TIMEOUT_MS` (25 000) был объявлен в `ENV` и
+   задокументирован (README, `ASSISTANT_ARCHITECTURE.md:§5`), но **нигде не
+   использовался**: `orchestrator.js` не передавал `timeoutMs` в `stage1`, а
+   `stage2Generate` его не принимал. Фактически работал только общий дедлайн 40 с.
+3. **🟡 `orchestrator.js:205`** — `clientIp` брал **последний** элемент
+   `X-Forwarded-For` (ближайший хоп) вместо первого (исходный клиент). Влияет
+   только при заданном `ASSIST_TRUSTED_PROXY_CIDR` (по умолчанию пусто).
+4. **🟡 `orchestrator.js:317,328`** — мёртвая ветка дедупа (`handleAssistAgain` —
+   заглушка); в однопоточном JS недостижима.
+5. **🟢** кэш ответов без TTL/лимита (`orchestrator.js:306`); `npm test` покрывает
+   только прокси/`health` (LLM-пайплайн без юнит-тестов); `fetchIndex` без лимита
+   размера; `FORWARD_HEADERS` без `etag/last-modified`; при `aborted` отдаётся
+   нестандартный HTTP 499.
+
+## Исправлено (2 пункта)
+
+### 1. `search.js` — порядок суффиксов подресурсов
+
+Массив `knownSubs` вынесен в `KNOWN_RESOURCE_SUBS`, отсортирован по убыванию длины
+при загрузке модуля. Проверено изолированно:
+`nubes_s3_sub_user → s3` (было `s3_sub`), `nubes_mariadb_sub_user → mariadb`;
+`nubes_postgres_database → postgres`, `nubes_postgres → postgres` — без изменений.
+
+### 2. `assist.js` + `stage1.js` + `orchestrator.js` — реальный per-call таймаут
+
+- `llmChat` получил параметр `timeoutMs` (дефолт `ENV.ASSIST_LLM_TIMEOUT_MS`) и
+  составной сигнал: дочерний `AbortController`, абортящийся по таймауту ИЛИ по
+  аборту вызывающего. Таймаут покрывает вызов целиком (в т.ч. чтение тела).
+- Таймаут отдаётся отдельным кодом **`llm_timeout`** (отмена клиентом/дедлайн —
+  по-прежнему `aborted`), чтобы `stage2` различал причины и корректно решал о повторе.
+- `stage1.js` освобождён от дублирующего `AbortController`.
+- `orchestrator.js`: `llm_timeout` → HTTP **504**.
+
+Проверено на локальном «зависшем» сервере: таймаут → `llm_timeout` (314 мс при
+лимите 300), abort родителя → `aborted` (152 мс). `node -c` всех модулей OK,
+`node --test` 4/4.
+
+## Проверка на живом стенде
+
+- `redeploy` инстанса `tf-docs` (`7a48a863-…`) через `llm_project/tests/redeploy.js`
+  → успешно (`finish=2026-10-12T07:56:44+03:00`, `ok=true`); `/health` → 200.
+- Прогон 62 вопросов на `nubes-test` (`--out RESULTS_AFTER_FIX`):
+  **62/62 — 200 OK**, шаблон **62/62**, ошибок 0; задержки p50 5.9 с,
+  p95 10.8 с, max 12.4 с; `llm_timeout` не срабатывал ни разу.
+- ⚠️ Сравнение с прежним `RESULTS_LIVE.json` **некорректно**: тот от 2026-10-07,
+  за 5 дней индекс документации изменился (у 45 из 62 вопросов другой набор
+  источников) → это дрейф индекса, а не эффект правки.
+
+## Что НЕ менялось (осознанно)
+
+Пункты 3–5 из «Найдено» (XFF, мёртвая ветка дедупа, кэш без TTL, юнит-тесты) —
+оставлены как есть: не мешают текущей работе; вернуться при масштабировании/переработке.