[2026-09-26] eagle: family/how-to/truenas-infrastructure.md personal/plans/balda-mm-pr-plan.md personal/projects/balda/balda-mattermost-connector.md personal/projects/balda/balda-mm-delegation-plan.md personal/tech/balda-go-fx-pitfalls.md

This commit is contained in:
Alexey Martemyanov committed 2026-09-26 14:57:15 +06:00
1 parent 036e7a7091
commit 1bf8320446
5 files changed
+318 -57

No files matched your search

@@ -1,30 +1,25 @@
# Balda — Mattermost коннектор (архитектура)
> Создано 2026-09-26. Обновлено 2026-09-26 (сессия PR-подготовки, завершена).
> Статус: **🟡 КОД ГОТОВ К PR — 6 коммитов, все гейты зелёные. Осталось одно решение: `tools/` в ветке.**
> 🟢 **Сессия PR-подготовки завершена:** починены 2 дефекта **в коде** (идемпотентный
> `MattermostSubject`; `ProgressPolicy.Typing`), написаны 6 файлов тестов (~90 тестов)
> на транспорт + хендлер, обновлены README / `docs/balda.md` и создан `docs/mattermost.md`.
> `golangci-lint` = 0 issues, `go-arch-lint` = OK.
> 🔴 **Блокер PR:** в ветке 16 файлов `tools/` из базового коммита `004fda2f` — в апстриме
> такого каталога нет. Нужно `git rm -r --cached tools/` по команде Alex (заблокировано
> истёкшим апрувом). Детали, коммиты и варианты — [[personal/plans/balda-mm-pr-plan]].
> Создано 2026-09-26. Обновлено 2026-09-26 (PR открыт).
> Статус: **✅ PR ОТКРЫТ — baldaworks/balda#8, 8/8 CI PASS, MERGEABLE.**
> 🟢 **PR:** https://github.com/baldaworks/balda/pull/8 — 41 файл, +5622/−18, 7 коммитов.
> Фаза 2 закрыта полностью: код, 103 новых теста, доки, зелёный CI.
> Блокер `tools/` снят: `/tools/` в `.gitignore` + `git rm -r --cached tools/`.
> Детали — [[personal/plans/balda-mm-pr-plan]].
> Часть проекта [[personal/projects/balda/balda-mm-delegation-plan]] (Фаза 2).
> Требование Alex: поддержка **всех** функций Балды, по новым API, production-качество.
>
> **Проверено (2026-09-26, финал):**
> - `go build ./...` → exit 0, `go vet ./...` → exit 0
> **Проверено (2026-09-26, PR):**
> - `go build ./...` → exit 0 · `go vet ./...` → exit 0
> - `go tool golangci-lint run` → **0 issues**
> - `go tool go-arch-lint check --project-path .` → **OK - No warnings found**
> - **DI-граф собирается целиком** с `balda.mattermost.enabled=true` — проверено реальным
> - **DI-граф собирается целиком** с `balda.mattermost.enabled=true` — проверено
> `validateBaldaApplication(prepared)` через fx, а не только компиляцией
> - 3 новых теста зелёные (см. §«Тесты»)
> - Закоммичено: `004fda2f feat(mattermost): add Mattermost transport adapter` (40 файлов, +3072)
> - **103 новых теста** зелёные, включая `-race`; в CI — 126 PASS, 0 FAIL, 0 SKIP
> - **CI: 8/8 джобов PASS** на чистом раннере (`.github/workflows`)
>
> **Осталось:** ничего по коду. Дальше — Фаза 3 (Балда с MM на Kraken) и Фаза 4 (исполнитель).
>
> 🔴 **ОБНОВЛЕНО 2026-09-26 (ночь, позже): «все quality gates пройдены» оказалось неполным.**
> При первом **живом запуске** на Kraken (Фаза 3) Балда ушла в crash-loop:
> 🔴 **Исторический урок (Фаза 3):** «все quality gates пройдены» оказалось неполным —
> при первом **живом запуске** на Kraken Балда ушла в crash-loop:
> `advertised commands have no actor handler: goal`. В `Advertisement.Names` была объявлена
> несуществующая команда `goal` (это payload kind, а не имя хендлера; цикл называется
> `goalkeeper`). **Ни `go build`, ни `go vet`, ни `golangci-lint`, ни `go-arch-lint`, ни
@@ -32,13 +27,23 @@
> `inbound.go` дельтой `tools/deltas-goal-command-fix.json`. Разбор —
> [[personal/tech/balda-go-fx-pitfalls]] §«Дефект 4».
> 📌 Вывод: «Фаза 2 закрыта» означала «код компилируется и граф собирается», но **не**
> «транспорт работает». Живой запуск обязателен. Текущий статус Фазы 3 —
> «транспорт работает». Живой запуск обязателен. Статус Фазы 3 —
> [[personal/projects/balda/balda-kraken-mm-deploy]].
>
## ✅ PR-ПРОХОД 2026-09-26 — транспорт приведён к PR-качеству
Ветка `feat/mattermost-channel`, **6 коммитов**, готово к `git push` и PR.
Подробности — [[personal/plans/balda-mm-pr-plan]].
Ветка `feat/mattermost-channel`, **7 коммитов**, PR **открыт** — baldaworks/balda#8.
Подробности и полный список — [[personal/plans/balda-mm-pr-plan]].
```
9f1e6c9c chore: ignore local project-editing tooling ← уборка tools/ из PR
58f27120 docs(mattermost): document the transport setup and behavior
80d4f41d test(mattermost): cover the transport, the ingress and the handler
c7f18654 fix(mattermost): send a monotonic seq on every client frame
6dc3077a feat(mattermost): add the inbound handler and wire it into DI
fa1a2855 feat(auth): support the Mattermost channel subject
004fda2f feat(mattermost): add Mattermost transport adapter ← база прошлой сессии
```
**Исправлено в коде (не в данных):**
@@ -47,12 +52,13 @@
| 🔴 Двойной префикс `principal` — прошлый фикс был в БД и вернулся | `auth.MattermostSubject()` теперь **идемпотентен** (срезает `mattermost:` перед повторной квалификацией); из `handler.go` убран `TrimPrefix`-костыль |
| `ProgressPolicy.Typing: true` в command-пути | Приведено к `false` — у ботов MM нет typing API, `SendTyping` осознанный no-op |
**Тесты — 6 новых файлов, ~90 тестов:** `locator_codec_test.go`, `inbound_test.go`,
`adapter_test.go`, `client_test.go`, `ingress_test.go` (в пакете транспорта) +
`handlersfx/mattermost_ingress_test.go`. Ключевые регрессионные guard'ы:
**Тесты — 6 новых файлов, 103 теста:** `locator_codec_test.go` (15), `inbound_test.go` (18),
`adapter_test.go` (17), `client_test.go` (13), `ingress_test.go` (23) +
`handlersfx/mattermost_ingress_test.go` (17). Ключевые регрессионные guard'ы:
`writeEvent` всегда с `seq` и уникальный `seq` под 16 горутинами (`bad_seq`),
plain-fallback только на content-rejection (не на 5xx), идемпотентность subject'а,
тред = одна сессия ≠ канальной, `/start` доступен до авторизации.
Пакеты `mattermost` + `handlersfx` в verbose-прогоне: **126 PASS, 0 FAIL, 0 SKIP**.
**Доки:** README + `docs/balda.md` + новый **`docs/mattermost.md`** (создание бота,
минтинг токена, membership, 5 ключей, поведение, troubleshooting).
@@ -65,11 +71,13 @@ go tool golangci-lint run → 0 issues
go tool go-arch-lint check --project-path . → OK - No warnings found
go test -race (затронутые пакеты) → все ok
```
⚠️ 5 пакетов падают (`cmd/balda`, `apps/balda`, `mcpruntime`, `session`, `state`) —
⚠️ 5 пакетов падают локально (`cmd/balda`, `apps/balda`, `mcpruntime`, `session`, `state`) —
**это апстримная база**, проверено `git stash` (те же 4 теста падают без правок).
🔴 **В CI эти же тесты ПРОШЛИ** — локальное падение было особенностью машины, не дефектом.
⚠️ `tools/mm-*.sh` + `tools/deltas-*.json` оставлены **незакоммиченными** — локальный
инструментарий, в PR не идёт.
**`tools/` вычищен из ветки:** `/tools/` в `.gitignore` + `git rm -r --cached tools/`
(коммит `9f1e6c9c`). Файлы на диске целы (39 шт.), в PR-diff их нет.
⚠️ `gitignore` **не отвязывает** уже отслеживаемые файлы — нужны оба шага.
---