diff --git a/README.md b/README.md index 6aff04d..d03f63b 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Система учёта рабочего времени сотрудников и контроля проектов для проектного отдела. +> 🌟 **Общая цель проекта — [docs/superpowers/PROJECT_GOAL.md](docs/superpowers/PROJECT_GOAL.md).** Возвращаться к этому документу каждый раз когда фокус сбивается. + ## Контекст Инициатива объединяет данные четырёх систем-источников в единое read-only аналитическое хранилище для ответов на главные вопросы руководителя проектного отдела: diff --git a/docs/superpowers/PROJECT_GOAL.md b/docs/superpowers/PROJECT_GOAL.md new file mode 100644 index 0000000..1eba8d8 --- /dev/null +++ b/docs/superpowers/PROJECT_GOAL.md @@ -0,0 +1,95 @@ +# Project Goal — Северная звезда проекта `bit-flight-deck` + +> **Назначение этого документа:** возвращаться сюда каждый раз когда возникает сомнение «правильно ли мы идём», «куда мы хотим прийти», «что главное». Если фокус сбился — этот файл возвращает на курс. + +## Что мы строим + +Система автоматизации для руководителя проектного отдела ИТ-компании. Объединяет данные 4 учётных систем (BIT.RA, EVA Desk, Битрикс24, самописная финрезная 1С) в единое read-only хранилище и даёт **автоматические ответы** на главные операционные вопросы. + +## Зачем (the Why) + +Сейчас руководитель проектного отдела отвечает на эти вопросы вручную через 3-4 системы + Excel. Это: +- не масштабируется (часов в неделе не хватает на сводку); +- не даёт прогноза (только реакция постфактум); +- даёт ответы с задержкой — часто пропускает критические сигналы вовремя. + +**Цель проекта — автоматизация принятия операционных решений**, освобождение руководителя от ручного сбора данных, проактивная сигнализация о проблемах. + +## К чему хочу прийти (end state, через ~3-6 месяцев) + +1. **Открыл утром дашборд — увидел всё:** кто загружен, кто свободен, какие проекты в риске, какая маржа, что подписывать в следующем месяце, прогноз финреза. +2. **Получил уведомление вовремя:** задача подвисла → Telegram-алёрт. Сделка ушла в реализацию без проектной команды → алёрт. Этап просрочен → алёрт. +3. **Прогноз вместо реакции:** вижу что через 3 недели у команды X простой, а в Битриксе квалифицированных сделок на Y часов — могу принять решение заранее. +4. **Финрез по подразделениям автоматически**, без месячного ручного Excel-сводения. +5. **Компетенции команды объективны** — выводятся из истории работ, не из «как сам себя оценил». + +## Главные бизнес-вопросы которым отвечает система + +| Вопрос | MVP / Подсистема | +|---|---| +| Кто из сотрудников сейчас загружен коммерческими работами? | MVP-1 | +| На какой период загружен и до когда? | MVP-1 | +| Сколько часов может прилететь из сделок Битрикса? | MVP-1 | +| Какие задачи подвисают и тормозят следующие работы? | MVP-2 | +| В каком состоянии проекты по срокам, с декомпозицией до задачи? | MVP-2 | +| Какая маржа проектов (план/факт)? | MVP-3 | +| Сколько НЗП (незавершёнки) на проектах? | MVP-3 | +| Сколько денег будем актировать в следующем месяце? | MVP-3 | +| Какой финрез у каждого подразделения? | MVP-4 | +| Прогноз финреза на основе загрузки? | MVP-4 | +| Кто из сотрудников реально что умеет (компетенции)? | Подсистема D | + +## Принципы (используются для разрешения спорных решений) + +1. **Автоматизация, не digital Excel.** Если вижу таблицу которую пользователь должен фильтровать руками — это не цель. Дашборд = ответы без фильтрации. + +2. **Read-only из источников.** Не строим параллельный учёт, не вводим данные дважды. Источники остаются мастерами. + +3. **Email — главный ключ identity** между всеми системами. Если в каком-то источнике email пуст — это организационная задача дозаполнить, а не повод писать сложный fuzzy-маппер. + +4. **Вертикальный срез по MVP.** Каждый MVP за 2-4 недели даёт **видимый дашборд + алёрты**, не «фундамент на 3 месяца без результата». Если MVP не даёт ответа на конкретный бизнес-вопрос — нужно либо переосмыслить MVP, либо запретить запускать. + +5. **Компетенции — производная.** Из реальных работ (`core.work_log`), не из ручного справочника. Ручные справочники компетенций — антипаттерн. + +6. **Single-user MVP.** Multi-user, RLS, персональные дашборды — вне scope. Когда понадобится — будет отдельный проект. + +7. **Используем существующую инфру.** PostgreSQL, N8N, Cloudflare Tunnel, LiteLLM, Gitea — всё это уже стоит в `~/infrastructure/`. Не дублируем. + +## Возврат к этому документу — checklist «фокус не сбился» + +Признаки **сбившегося фокуса** (пора открыть этот файл и пересверить): + +- ✖ Обсуждаем "крутую техническую вещь" которая не отвечает ни на один из 11 бизнес-вопросов выше. +- ✖ Строим инфраструктуру "на вырост" без видимого MVP за 2-4 недели. +- ✖ Возвращаемся к ручной фильтрации таблиц вместо автоматических ответов. +- ✖ Углубляемся в один источник, теряя картину всех 4 (или общую цель). +- ✖ Проектируем фичу для воображаемых будущих пользователей вместо одного руководителя проектного отдела. +- ✖ Пытаемся синхронизировать что-то "потому что можно", а не потому что нужно для бизнес-вопроса. +- ✖ Создаём ручной справочник там где можно вывести из данных. + +Если хоть один пункт совпадает — пауза, откат, чтение этого файла, переоценка. + +## Roadmap высокоуровневый + +| MVP/Phase | Бизнес-выход | Спек | +|---|---|---| +| MVP-1 | Дашборд загрузки сотрудников (4 слоя) | [specs/2026-05-13-mvp1-workload-design.md](specs/2026-05-13-mvp1-workload-design.md) | +| MVP-2 | Подвисшие задачи + контроль сроков + Telegram-алёрты | [specs/2026-05-13-mvp2-deadlines-design.md](specs/2026-05-13-mvp2-deadlines-design.md) | +| MVP-3 | Маржа, НЗП, прогноз актирования | [specs/2026-05-13-mvp3-finance-design.md](specs/2026-05-13-mvp3-finance-design.md) | +| MVP-4 | Финрез по подразделениям (с отдельным мозговым штурмом) | [specs/2026-05-13-mvp4-finrez-design.md](specs/2026-05-13-mvp4-finrez-design.md) | +| Subsystem D | Компетенции команды как производная из истории работ | [specs/2026-05-13-subsystem-d-competence-design.md](specs/2026-05-13-subsystem-d-competence-design.md) | + +## Что вне scope (никогда, или не в этом проекте) + +- ❌ Замена BIT.RA / EVA / Битрикса. Это **аналитический слой поверх**, не новая ERP. +- ❌ Multi-user интерфейс. Пользователь один — Руководитель проектного отдела. +- ❌ Расширение функционала источников. Если что-то нужно добавить в BIT.RA / EVA — это отдельные задачи, не часть этого проекта. +- ❌ Mobile app, web frontend для сотрудников. Метабейс + NocoDB через браузер — достаточно. +- ❌ Алгоритмы предсказания на ML/AI до тех пор, пока не разберёмся со статистикой простыми SQL. + +## Связанные документы + +- **Спеки MVP** — в [specs/](specs/). +- **План реализации MVP-1** — в [plans/2026-05-13-mvp1-workload.md](plans/2026-05-13-mvp1-workload.md). +- **Конфигурация MVP-1** (whitelist'ы сотрудников, SD-проектов, стадий) — в [specs/mvp1-config.md](specs/mvp1-config.md). +- **Декомпозиция и архитектурные решения** — в memory-системе агента (`project_workload_control`, `architecture_*`, `feedback_*`). diff --git a/docs/superpowers/specs/2026-05-13-mvp1-workload-design.md b/docs/superpowers/specs/2026-05-13-mvp1-workload-design.md index 661b523..e1ad36f 100644 --- a/docs/superpowers/specs/2026-05-13-mvp1-workload-design.md +++ b/docs/superpowers/specs/2026-05-13-mvp1-workload-design.md @@ -454,15 +454,17 @@ Materialized views, обновляемые после каждой пачки sy - **Дисциплина EVA**: внедрить в команде заполнение `plan_start_date` / `plan_end_date` / `deadline` / `responsible_id` для всех новых задач. Через 2-3 месяца — пересмотр MVP-1 с честной «плановой» через plan_start_date. - **Email во всех системах**: дозаполнить email сотрудников в BIT.RA `Catalog.Пользователи` где пусто. Аналогично в Битриксе для новых юзеров. -## 13. Open questions / TODO +## 13. Open questions / TODO — закрыто (2026-05-13) - ✅ **Имя проекта** — `bit-flight-deck`. Gitea-репозиторий `bit-flight-deck`. Локальная папка `~/projects/bit-flight-deck/`. - ✅ **Поддомен для Bitrix-webhooks** — `n8n.bigmadnekenny.ru`. Добавить ingress-роут в cloudflared `host-systemd`. -- **Список ~20 сотрудников MVP-1.** Какие конкретно email/department-id попадают в фокус? До начала разработки — выписать явный whitelist. -- **3 SD-проекта.** Извлечь точные ID/коды из `https://gitea.bigmadnekenny.ru/admin/eva-bot/docs/`. -- **Стадии Битрикса для прогноза.** Подтвердить точный список стадий CAT=16, в которых сделка должна учитываться в прогнозе. Кандидаты: `FINAL_INVOICE` («Защита сделки»), `UC_A02TUT` («Отложено»), `UC_U68WK1` («Подготовка рамочного договора»). Стадии `UC_XPZ8Z5/UC_QYTFP3` (Реализация) — туда уже EVA, в прогноз НЕ включаем. -- **Заполняемость email в BIT.RA.** Через MCP проверить какой % пользователей имеет email в `КонтактнойИнформации`. Если ниже 80% — параллельная организационная задача. -- **Распределение часов сделки по проектной команде.** Базовая логика — поровну между членами команды. Веса можно править в NocoDB. Возможно нужна более умная логика (по компетенциям) — это backlog для подсистемы D. +- ✅ **Список сотрудников MVP-1** — 15 email подтверждены пользователем + 1 TBA. Полный список в [mvp1-config.md](mvp1-config.md). Применяется через `sql/seed/mvp1_target_employees.sql`. +- ✅ **3 SD-проекта EVA** — `pbsd`, `sd-perm`, `sd-czentralnyj`. Применяется через `sql/seed/sd_projects_whitelist.sql`. +- ✅ **Стадии Битрикса CAT=16 для прогноза** — `C16:UC_A2446J` (Оценка и подготовка КП), `C16:FINAL_INVOICE` (Защита сделки), `C16:UC_U68WK1` (Подготовка рамочного договора). Применяется через `sql/seed/bitrix_forecast_stages.sql`. `UC_A02TUT` (Отложено) и стадии Реализации **НЕ включены** (двойной счёт с EVA). +- ✅ **Заполняемость email в BIT.RA** — пользователь подтверждает «все заполнены или будут заполнены к запуску MVP-1». Через MCP не проверяемо, но это организационная гарантия. ETL пишем в предположении что email есть. + +Остающиеся внутренние: +- **Распределение часов сделки по проектной команде.** Базовая логика — поровну между членами команды. Веса можно править в NocoDB. Более умная логика (по компетенциям) — backlog для Подсистемы D. ## 14. Backlog после MVP-1 diff --git a/docs/superpowers/specs/mvp1-config.md b/docs/superpowers/specs/mvp1-config.md new file mode 100644 index 0000000..8fbb4de --- /dev/null +++ b/docs/superpowers/specs/mvp1-config.md @@ -0,0 +1,68 @@ +# MVP-1 Configuration — Whitelists и точные коды + +> **Назначение:** конкретные значения для конфигурации MVP-1. Меняются по мере добавления/удаления сотрудников, проектов, стадий. Не зашиваем в спеку (она про дизайн), а живут здесь — отдельным конфигом. SQL-файлы в `sql/seed/` импортируют эти значения. + +## Сотрудники MVP-1 — whitelist по email + +Команда РП-2 и связанные. Перечень от пользователя на 2026-05-13. + +| # | Email | +|---|---| +| 1 | `AleUZhukov@1cbit.ru` | +| 2 | `AKPetyanina@1cbit.ru` | +| 3 | `AAGevorgyan@1cbit.ru` | +| 4 | `AAPrilukov@1cbit.ru` | +| 5 | `VVGaspirovich@1cbit.ru` | +| 6 | `VDKhaldin@1cbit.ru` | +| 7 | `VUKozlov@1cbit.ru` | +| 8 | `GATokareva@1cbit.ru` | +| 9 | `DSBulychev@1cbit.ru` | +| 10 | `dmvmikhaylov@1cbit.ru` | +| 11 | `EASenik@1cbit.ru` | +| 12 | `ZGalihanova@1cbit.ru` | +| 13 | `IAGadzhiev@1cbit.ru` | +| 14 | `LAYagudina@1cbit.ru` | +| 15 | `SYaMamedbakova@1cbit.ru` | +| 16 | (TBA — будет добавлен) | + +Применение: см. `sql/seed/mvp1_target_employees.sql`. + +## SD-проекты EVA — явный список + +Известны через URL в EVA (предоставлены пользователем): + +| EVA Project code | URL | Описание | +|---|---|---| +| `pbsd` | https://firstbit.evateam.ru/project/Project/pbsd | Центр поддержки офиса Екатеринбург Проектный центр | +| `sd-perm` | https://firstbit.evateam.ru/project/Project/sd-perm | SD Пермь | +| `sd-czentralnyj` | https://firstbit.evateam.ru/project/Project/sd-czentralnyj | SD Центральный | + +Эти 3 проекта — единственные SD-проекты. Все остальные `CmfProject` — обычные PM-проекты, даже если `enable_sdesk` пустое. + +Применение: см. `sql/seed/sd_projects_whitelist.sql`. + +## Стадии Битрикса CAT=16 для прогнозной загрузки + +| STAGE_ID (полный) | NAME | Используется в прогнозе | +|---|---|---| +| `C16:UC_A2446J` | Оценка и подготовка КП | ✅ | +| `C16:FINAL_INVOICE` | Защита сделки | ✅ | +| `C16:UC_U68WK1` | Подготовка рамочного договора | ✅ | + +Не включаем в прогноз: +- Более ранние стадии (NEW «Wish-List», PREPARATION «Проработка», PREPAYMENT_INVOIC «Квалификация», EXECUTING «Уточнение требований») — слишком ранняя стадия, ещё не подтверждено что будет проект. +- `UC_A02TUT` «Отложено» — пауза, неопределённость, не считаем загрузку. +- `UC_XPZ8Z5` «Реализация первого этапа проекта», `UC_QYTFP3` «Реализация проекта» — это уже **фактическая загрузка через EVA**, не прогноз (двойной счёт нельзя). +- `WON`, `LOSE`, `APOLOGY` — закрытые, не считаем. + +Применение: см. `sql/seed/bitrix_forecast_stages.sql`. + +## Email в BIT.RA — статус + +**От пользователя:** через MCP проверить невозможно, но email сотрудников **все заполнены или будут заполнены к моменту запуска MVP-1**. Это организационная гарантия — на ETL пишем код в предположении что email есть для всех целевых сотрудников. + +Fallback (если кто-то всё-таки без email): запись в `core.identity_map` с `confidence='manual'`, ждёт ручного разрешения через NocoDB. + +## История изменений + +- **2026-05-13:** первая версия. 15 email + 1 TBA. 3 SD-проекта. 3 стадии Битрикса. diff --git a/sql/seed/bitrix_forecast_stages.sql b/sql/seed/bitrix_forecast_stages.sql new file mode 100644 index 0000000..a670491 --- /dev/null +++ b/sql/seed/bitrix_forecast_stages.sql @@ -0,0 +1,25 @@ +-- bitrix_forecast_stages.sql +-- Помечает сделки Битрикса CAT=16 в нужных стадиях флагом is_in_forecast=true для прогнозной загрузки. +-- Whitelist стадий — см. docs/superpowers/specs/mvp1-config.md + +-- Сбрасываем флаг +UPDATE core.deal SET is_in_forecast = false; + +-- Включаем в прогноз только 3 стадии CAT=16 +UPDATE core.deal +SET is_in_forecast = true +WHERE category_id = 16 + AND stage_id IN ( + 'C16:UC_A2446J', -- Оценка и подготовка КП + 'C16:FINAL_INVOICE', -- Защита сделки + 'C16:UC_U68WK1' -- Подготовка рамочного договора + ); + +-- Проверка +DO $$ +DECLARE + n int; +BEGIN + SELECT count(*) INTO n FROM core.deal WHERE is_in_forecast = true; + RAISE NOTICE 'Bitrix deals in forecast: %', n; +END $$; diff --git a/sql/seed/mvp1_target_employees.sql b/sql/seed/mvp1_target_employees.sql new file mode 100644 index 0000000..2cbfdab --- /dev/null +++ b/sql/seed/mvp1_target_employees.sql @@ -0,0 +1,40 @@ +-- mvp1_target_employees.sql +-- Помечает целевых сотрудников MVP-1 флагом is_target_for_mvp1=true. +-- Запускать ПОСЛЕ синхронизации core.employee из BIT.RA, чтобы emails уже были в таблице. +-- Whitelist — см. docs/superpowers/specs/mvp1-config.md + +-- Сбрасываем флаг у всех (на случай если кого-то убирают из MVP-1) +UPDATE core.employee SET is_target_for_mvp1 = false; + +-- Помечаем целевых +UPDATE core.employee +SET is_target_for_mvp1 = true +WHERE lower(email) IN ( + lower('AleUZhukov@1cbit.ru'), + lower('AKPetyanina@1cbit.ru'), + lower('AAGevorgyan@1cbit.ru'), + lower('AAPrilukov@1cbit.ru'), + lower('VVGaspirovich@1cbit.ru'), + lower('VDKhaldin@1cbit.ru'), + lower('VUKozlov@1cbit.ru'), + lower('GATokareva@1cbit.ru'), + lower('DSBulychev@1cbit.ru'), + lower('dmvmikhaylov@1cbit.ru'), + lower('EASenik@1cbit.ru'), + lower('ZGalihanova@1cbit.ru'), + lower('IAGadzhiev@1cbit.ru'), + lower('LAYagudina@1cbit.ru'), + lower('SYaMamedbakova@1cbit.ru') +); + +-- Проверка: должно быть >= 15 (если не хватает — кто-то не попал из BIT.RA, разбираться). +DO $$ +DECLARE + n int; +BEGIN + SELECT count(*) INTO n FROM core.employee WHERE is_target_for_mvp1 = true; + RAISE NOTICE 'MVP-1 target employees marked: %', n; + IF n < 15 THEN + RAISE WARNING 'Expected at least 15 target employees, got %. Check unmatched emails.', n; + END IF; +END $$; diff --git a/sql/seed/sd_projects_whitelist.sql b/sql/seed/sd_projects_whitelist.sql new file mode 100644 index 0000000..c686b4e --- /dev/null +++ b/sql/seed/sd_projects_whitelist.sql @@ -0,0 +1,24 @@ +-- sd_projects_whitelist.sql +-- Помечает SD-проекты EVA флагом is_sd=true. +-- Запускать ПОСЛЕ синхронизации core.project, чтобы коды уже были в таблице. +-- Whitelist — см. docs/superpowers/specs/mvp1-config.md + +-- Сбрасываем флаг у всех (на случай корректировок) +UPDATE core.project SET is_sd = false; + +-- Помечаем SD-проекты по коду EVA +UPDATE core.project +SET is_sd = true +WHERE eva_code IN ('pbsd', 'sd-perm', 'sd-czentralnyj'); + +-- Проверка +DO $$ +DECLARE + n int; +BEGIN + SELECT count(*) INTO n FROM core.project WHERE is_sd = true; + RAISE NOTICE 'SD projects marked: %', n; + IF n != 3 THEN + RAISE WARNING 'Expected 3 SD projects, got %. Check eva_code for pbsd/sd-perm/sd-czentralnyj.', n; + END IF; +END $$;