iistwin/IMPLEMENTATION_LOG.md

IMPLEMENTATION_LOG — доведение iistwin до коммерческой готовности

Контекст для любого ИИ-агента / разработчика

Проект: iistwin (TaskTitan) — CRM/таск-трекер. Стек: React 18 + TypeScript + Vite + Wouter + TanStack Query + shadcn/ui (клиент client/src), Express + Drizzle ORM + PostgreSQL с мультитенантностью через organizationId (сервер server/), JWT (access + refresh), SSE real-time. Миграции — детерминированный SQL-раннер в migrations/ (scripts/migrate-docker.js, НЕ drizzle-kit). Деплой: push в main → GitHub Actions deploy.yml → Docker на VPS 82.202.130.22 (прод: https://iistwin.ru). Финансы — субапп /di2 (client-di2/ + server/finance-di2/).

Инвариант (жёсткое требование владельца): механика мгновенного глобального поиска — на главной (client/src/components/HomeGlobalSearch.tsx), в реестре задач (TaskRegistry.tsx) и в канбане (TaskKanban.tsx) — НЕ должна измениться ни в поведении, ни в скорости ощущений. API GET /api/tasks?search=&limit= и подстроковая семантика поиска (ilike '%…%' находит совпадения внутри слов, «омент» → «моментально») сохраняются. Ускорение поиска — только через pg_trgm GIN-индексы, НЕ через tsvector (он меняет семантику).

Источники: этот лог ведётся по плану «план улучшения до продакт.md» (аудит production-готовности) и исполнительному плану Kimi Code. Нумерация шагов ниже соответствует исходному плану (Фаза 0: 0.0–0.15, Фаза 1: 1.1–1.10, Фаза 2: 2.1–2.5). Дополнительный шаг A3 (подключение тестов) вынесен вперёд из 1.6.

Принятые решения:

• Биллинг (0.13): только абстракция PaymentProvider + MockPaymentProvider; реальный эквайринг — позже, отдельным этапом.
• Шаг 0.14: серверные кастомизации — в отдельный приватный инфра-репозиторий (основной репозиторий остаётся как есть).

Как читать файл: записи идут в порядке выполнения (не обязательно совпадает с нумерацией). Каждая запись — по шаблону: статус, зачем, что изменено, ключевые файлы, коммит, как проверялось, влияние на поиск/UX, подводные камни. Ничего не менять без записи в этот лог.

---

[0.0] Обновить локальный репозиторий

• Статус: ✅ done
• Зачем: рабочая копия должна соответствовать актуальному main на GitHub.
• Что изменено: — (только проверка)
• Как проверялось: git fetch origin + git status (чисто, синхронизировано с origin/main, HEAD a2b231d), npm run check — зелёный (оба tsc: основной и client-di2).
• Влияние на поиск/UX: нет.

---

[0.15] Сквозная документация изменений (этот файл)

• Статус: ✅ done (коммит 76a0d85 «chore(docs): add implementation log»)
• Зачем: по одному файлу любой ИИ-агент понимает, что сделано, зачем, какие файлы тронуты и как проверялось.
• Что изменено: создан IMPLEMENTATION_LOG.md в корне репозитория (шапка-контекст + шаблон записей).
• Влияние на поиск/UX: нет.

---

[A3 / 1.6 частично] Подключение тестов + починка 5 падающих

• Статус: ✅ done
• Зачем: тесты существовали (3 файла, vitest), но не запускались ни локально (нет скрипта), ни в CI; 5 из 45 падали. Без зелёных тестов дальнейшие изменения безопасности/производительности — вслепую.
• Что изменено:
  • package.json — скрипт "test": "vitest run".
  • .github/workflows/pr-check.yml — шаг «Tests» (npm test) после type check.
  • server/utils/userActivity.ts — фикс реального бага: trackUserActivity мог кинуть синхронно внутри authenticateToken, исключение попадало в catch аутентификации → ложный 403 Недействительный токен на первом запросе пользователя за минуту. Тело обёрнуто в try/catch, throttle сбрасывается для повторной попытки (соответствие контракту fire-and-forget).
  • tests/auto-transitions.test.ts — 3 устаревших теста обновлены под намеренное текущее поведение (forward-only по position; синк assignee в task_assignees; системное сообщение заменено аудит-записью «Автопереход»), добавлен мок delegation.service.
• Как проверялось: npx vitest run — 45/45 зелёные; npm run check — чисто.
• Влияние на поиск/UX: нет.
• Подводные камни: баг в userActivity.ts проявлялся только на первом аутентифицированном запросе в минуту (throttle) — в проде мог давать sporadic 403.

---

[0.7] Обработчик ошибок без утечки деталей

• Статус: ✅ done
• Зачем: клиент не должен видеть SQL и внутренности БД в 5xx-ответах (аудит, Фаза 0).
• Что изменено:
  • server/index.ts — глобальный error handler: при status ≥ 500 отдаёт «Внутренняя ошибка сервера (код XXXXXXXX)», оригинальная ошибка — в серверный лог с тем же кодом инцидента. 4xx не тронуты.
  • Route-уровень (12 файлов): зачищены все 5xx-ответы с err.message/String(err)/телом апстрима — auth.users.routes.ts, form-offline.routes.ts, sync.routes.ts, polls.routes.ts, reactions.routes.ts, mcp-rag.routes.ts, llm-providers.routes.ts, external.routes.ts, task-crud-write.routes.ts, task-fields.routes.ts, finance-di2/routes.ts, documents/worker/server.ts. Где не было — добавлен console.error с контекстом.
• Как проверялось: повторный grep status(5xx) + err.message по server/ — 0 совпадений; npm run check чисто; npx vitest run 45/45.
• Влияние на поиск/UX: нет (только тексты 5xx-ответов).
• Подводные камни: остались ответы 200 + success:false с err?.message (llm-providers, rag, finance-di2) и 4xx с err.message (documents, data-tables) — сознательно вне скоупа шага, кандидаты для фазы 2.

---

[0.8] Убрать passwordHash из выдачи пользователей

• Статус: ✅ done
• Зачем: хэши паролей и токены не должны уходить клиенту (в т.ч. через offline-sync).
• Что изменено:
  • shared/schema.ts — тип SafeUser (User без passwordHash/verificationToken/resetPasswordToken/resetPasswordExpires) + набор колонок safeUserColumns (единая точка правды).
  • server/storage/users.storage.ts — getUsersByOrganization и listUsers → SafeUser[].
  • server/storage/social.storage.ts (searchUsers), server/storage/task-meta.storage.ts (getUsersByRole, getUsersByOrgRoleId), server/documents/data-resolution.service.ts (getUser для шаблонов) — тоже на safeUserColumns.
  • Сигнатуры в server/storage.ts; типовые правки у caller'ов (логика не менялась). Методы аутентификации (где passwordHash нужен) не тронуты.
  • Побочный эффект: ctx.users.list() в автоматизациях и MCP list_users тоже sanitized.
• Как проверялось: ни один из 43 caller'ов не использовал исключённые поля (tsc); sync (initial + delta) теперь отдаёт пользователей без хэшей; npm run check чисто; npx vitest run 45/45; grep passwordHash по server/ — только auth-флоу.
• Влияние на поиск/UX: нет.
• Подводные камни: при явном списке колонок drizzle возвращает плоские строки даже с join — мёртвый маппинг в listUsers убран, на это опираться нельзя в будущих правках.

---

[0.11] Миграция индексов (0079_performance_indexes.sql)

• Статус: ✅ done
• Зачем: убрать Seq Scan на горячих путях — поиск задач, дельта-синк, история полей, логин по email.
• Что изменено: migrations/0079_performance_indexes.sql — CREATE EXTENSION IF NOT EXISTS pg_trgm; GIN (gin_trgm_ops) на tasks.title и tasks.description; (organization_id, updated_at DESC) и (form_id, updated_at) на tasks; field_history(task_id); users(email). Все с IF NOT EXISTS, без CONCURRENTLY (раннер в транзакции).
• Как проверялось: миграция применена на scratch-контейнере postgres:16-alpine с 100k синтетических задач — все 7 операторов чисто. EXPLAIN ANALYZE поиска ilike '%омент%' (совпадение внутри слова — инвариант): полный проход 77.5 мс (Seq Scan) → 4.8 мс (Bitmap Index Scan по trgm + BitmapAnd с org-индексом), ускорение ~16×; с LIMIT 50 — 10.8 мс → 9.7 мс. Отдельно проверено: CREATE EXTENSION pg_trgm выполняется не-суперпользователем-владельцем БД (trusted extension, PG 13+) — на проде миграция пройдёт под appuser.
• Влияние на поиск/UX: семантика НЕ меняется (тот же ilike, тот же API) — только скорость.
• Подводные камни: на проде построение GIN-индексов без CONCURRENTLY кратковременно блокирует запись в tasks — при текущих объёмах (десятки тысяч задач) это секунды, приемлемо.