[2026-09-26] eagle: personal/projects/balda/balda-mattermost-connector.md personal/projects/balda/balda-mm-delegation-plan.md personal/projects/balda/mattermost-kraken-deploy.md personal/tech/balda-go-fx-pitfalls.md

This commit is contained in:
Alexey Martemyanov committed 2026-09-26 11:14:40 +06:00
1 parent 06950241dd
commit e7091dd819
4 files changed
+286 -52

No files matched your search

@@ -1,18 +1,19 @@
# Balda — Mattermost коннектор (архитектура)
> Создано 2026-09-26. Обновлено 2026-09-26 (вечер). Статус: **КОД СОБИРАЕТСЯ, DI-ГРАФ ВАЛИДИРУЕТСЯ**.
> Создано 2026-09-26. Обновлено 2026-09-26 (вечер). Статус: **✅ ЗАКРЫТА — ВСЕ QUALITY GATES ПРОЙДЕНЫ**.
> Часть проекта [[personal/projects/balda/balda-mm-delegation-plan]] (Фаза 2).
> Требование Alex: поддержка **всех** функций Балды, по новым API, production-качество.
>
> **Проверено (2026-09-26):**
> **Проверено (2026-09-26, финал):**
> - `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` — проверено реальным
> `validateBaldaApplication(prepared)` через fx, а не только компиляцией
> - 3 новых теста зелёные (см. §«Тесты»)
> - Закоммичено: `004fda2f feat(mattermost): add Mattermost transport adapter` (40 файлов, +3072)
>
> **Осталось:** 2 шага — дописать ожидание маршрута Mattermost в `TestBuiltinRoutes`
> (единственная регрессия от наших правок) + `go tool golangci-lint run`.
> Подробности в §«🔴 Текущее состояние и следующий шаг».
> **Осталось:** ничего по коду. Дальше — Фаза 3 (Балда с MM на Kraken) и Фаза 4 (исполнитель).
>
> Разделы ниже — сначала контракт/разведка, затем **фактически написанные файлы**. Ищи
> §«Что фактически написано» для реестра файлов.
@@ -217,19 +218,23 @@ MM: `Source` = новый `turncmd.SourceMattermost`, `DeliveryFormat` = `Delive
---
## Что нужно добавить в shared-слой
## Что нужно добавить в shared-слой — ✅ ВСЁ ПРИМЕНЕНО
| Файл | Добавить |
|---|---|
| `deliverycmd/channel.go` | `ChannelTypeMattermost ChannelType = "mattermost"` |
| `deliveryfmt/routes.go` | `TransportMattermost = "mattermost"`, `NameMattermostMarkdown Name = "mattermost_markdown"` |
| `turncmd` (source) | `SourceMattermost` |
| `docs/commands.md` | колонка Mattermost в таблице доступности команд |
| `docs/balda.md` + `README.md` | описание нового транспорта (требование AGENTS.md) |
| Файл | Добавить | Статус |
|---|---|---|
| `deliverycmd/channel.go` | `ChannelTypeMattermost ChannelType = "mattermost"` | ✅ |
| `deliveryfmt/routes.go` | `TransportMattermost = "mattermost"`, `NameMattermostMarkdown Name = "mattermost_markdown"` | ✅ |
| `turncmd` (source) | `SourceMattermost` | ✅ |
| `docs/commands.md` | колонка Mattermost в таблице доступности команд | ✅ |
| `docs/reference/configuration.md` | 5 ключей `balda.mattermost.*` | ✅ |
| `README.md` / `docs/balda.md` | ⚠️ **не обновлялись** — README всё ещё перечисляет 3 chat surface | ⏳ |
⚠️ `channel/router.go` **править не нужно** — он map-based по `locator.ChannelType`.
Достаточно зарегистрировать binding в DI (группа `balda_delivery_channel_adapter`).
📌 Остаётся один незакрытый пункт требований `AGENTS.md` (не блокирующий): README и
`docs/balda.md` не упоминают Mattermost. Закрыть при подготовке PR в апстрим либо в Фазе 3.
---
## Что фактически написано (2026-09-26)
@@ -354,20 +359,66 @@ err = validateBaldaApplication(prepared) // ← вот это и есть
провайдер `balda_agent: opencode_acp`. Якорь `func TestValidateCommandRunsValidation(t *testing.T) {`
использован как точка вставки.
### 🔴 Текущее состояние и следующий шаг
### ✅ Текущее состояние — ЗАКРЫТО (2026-09-26, ночь)
**Осталось 2 шага (~5 минут):**
Оба ранее открытых пункта выполнены:
1. **Дописать ожидание маршрута Mattermost в `TestBuiltinRoutes`.**
`internal/apps/balda/deliveryfmt/registry_test.go`, функция `TestBuiltinRoutes`.
В map `want` добавить:
```go
{transport: TransportMattermost, deliveryFormat: DeliveryFormatNone}: NamePlainText,
```
Симптом без правки: `len(BuiltinRoutes()) = 5, want 4`.
Причина: в `routes.go` мы добавили маршрут Mattermost (строка 32), а тест-ожидание не обновили.
**Это единственная регрессия, внесённая нашими правками.**
2. `go tool golangci-lint run` — ещё не запускался.
1. ✅ **`TestBuiltinRoutes`** — в map `want` добавлен маршрут Mattermost
(`internal/apps/balda/deliveryfmt/registry_test.go`). Пакет `deliveryfmt` зелёный.
2. ✅ **`golangci-lint`** — запущен, 4 замечания → исправлены (см. §«Что дал golangci-lint» ниже).
Дополнительно в этом же заходе:
- ✅ **`.go-arch-lint.yml` обновлён** — компоненты `mattermost_transport` / `mattermost_wiring`,
права зависимости у `composition_root` и `ingress_wiring`. Требование `AGENTS.md`.
- ✅ **Удалён мёртвый typing-throttle** целиком (не заглушен).
- ✅ Закоммичено: `004fda2f feat(mattermost): add Mattermost transport adapter` (40 файлов, +3072).
**Ничего не осталось по коду.** Дальше — Фаза 3 (развернуть Балду с MM на Kraken,
провайдер DeepSeek) → [[personal/projects/balda/balda-mm-delegation-plan]].
### Что дал `golangci-lint` (4 замечания, все закрыты)
| Замечание | Файл | Фикс |
|---|---|---|
| `inamedparam` ×2 | `ingress.go:452-453` (interface assertion) | `Start(ctx context.Context) error` / `Stop(ctx context.Context) error` |
| `unused` | `adapter.go:149` `shouldSendTyping` | удалён вместе со всем throttle-механизмом |
| `unused` | `ingress.go:21` `websocketReceiveTimeout` | константа удалена |
| `unlambda` | `mattermostfx/module.go:51` обёртка `func(client, logger) *Adapter` | заменена на голое `mattermost.NewAdapter` |
**Корневая причина:** typing-throttle (`shouldSendTyping`, `typingThrottleInterval`,
`typingLastSentAt`, `typingMu`, `SetTypingThrottleInterval`) был скопирован из Zulip
по аналогии, но у MM-ботов **нет typing API** — `SendTyping` всегда `return nil`, значит
весь механизм недостижим. Удалён **целиком группой** (каскад: поле → setter → `sync` →
`zerolog` в `module.go`), а не заглушен `nolint`.
📌 **Урок для будущих транспортов:** при копировании Zulip-адаптера проверять каждую фичу
на применимость к провайдеру. Перенос «по аналогии» создаёт мёртвый код, который линтер
находит только на финальном прогоне. Детали — [[personal/tech/balda-go-fx-pitfalls]].
### `.go-arch-lint.yml` — что добавлено
Требование `AGENTS.md`: архитектурное изменение обязано обновлять arch-lint в том же коммите.
Без этого `go tool go-arch-lint check` падает двумя классами ошибок
(`composition_root shouldn't depend on …/mattermost`, `not attached to any component in archfile`).
4 правки по образцу `zulip`:
- `components:` → `mattermost_transport` (`channel/mattermost` + `presentation/`) и
`mattermost_wiring` (`mattermostfx/`)
- `mayDependOn` для обоих новых компонентов
- `composition_root` → `+ mattermost_transport, mattermost_wiring`
- `ingress_wiring` → `+ mattermost_transport`
Полные YAML-фрагменты — [[personal/tech/balda-go-fx-pitfalls]] §«go-arch-lint».
### ✅ Финальные quality gates — все зелёные
```
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
тесты Mattermost → 3 PASS
```
### ✅ Предсуществующие падения тестов — НЕ наши
@@ -398,14 +449,36 @@ err = validateBaldaApplication(prepared) // ← вот это и есть
6. **`commandSupport` переименован** в экспортируемый `IngressCommandSupport` (нужен для `fx.In`),
оставлен алиас.
### 🔴 Известный незакрытый шаг
### ✅ Импорт mattermostfx — ЗАКРЫТО
`internal/apps/balda/app.go` — модуль уже в списке, но **импорт не добавлен**:
`internal/apps/balda/app.go` — импорты добавлены (строки 27-28, рядом с `zulipfx`):
```go
"github.com/baldaworks/balda/internal/apps/balda/channel/mattermost"
"github.com/baldaworks/balda/internal/apps/balda/channel/mattermost/mattermostfx"
```
Вставить рядом с `zulipfx` (строки 27). LSP: `undefined: mattermostfx` на строке 667.
**Без этого `go build ./...` не пройдёт** — проверять первым делом.
Корневой `mattermost` нужен для `mattermost.ValidateConfig` в `validateMattermostConfig`.
`mattermostfx.Module` в списке модулей (строка ~667). `go build ./...` = exit 0.
### 🔴 Что понадобилось дополнительно (не было в исходном коде)
Первоначально модуль компилировался, но **DI-граф не собирался**. Три дефекта:
1. **`fx.In` нельзя аннотировать внешним `fx.ParamTags`.** `IngressParams` содержит `fx.In`,
а в `module.go` стоял `fx.Annotate(NewIngress, fx.ParamTags(...))` → fx падает с
`fx.In structs cannot be annotated with fx.ParamTags or fx.From`.
**Фикс:** `name:`-теги перенесены **в поля `IngressParams`**, `NewIngress` без `fx.Annotate`.
Так же сделано в `zulipfx` (`zulip.NewServer` идёт голой ссылкой, теги в `ServerParams`).
2. **Не хватало провайдеров registered strings.** Модуль запрашивает
`balda_mattermost_{server_url,token,bot_user_id,bot_username}` — их никто не предоставлял.
**Фикс:** 4 `fx.Provide` в `app.go` (блок `// Mattermost transport`), значения берутся из
`cfg.Balda.Mattermost.*` через `strings.TrimSpace`. Для несуществующих ключей
`GetString` возвращает `""` — тот же паттерн, что у `balda_zulip_*`.
3. **Валидация стояла не там.** Функцию `validateMattermostConfig` добавили в `app.go`
(рядом с `validateSlackConfig`), вызов — после `validateSlackConfig` в `Module()`.
**Метод, который это поймал:** `go build`/`go vet` этих ошибок **не видят** — только реальный
`fx.ValidateApp` через `validateBaldaApplication`. Для любого нового транспорта писать такой
тест сразу: он ловит неполный wiring, а не только синтаксис.
### Конфиг, который нужен для запуска
@@ -445,8 +518,20 @@ balda_mattermost_bot_username
| `tools/deltas-mattermost-4.json` | тест fx-графа |
| `tools/deltas-mattermost-5.json` | фикс `fx.In` + `module.go` |
| `tools/deltas-mattermost-6.json` | 4 провайдера строк |
| `tools/deltas-mattermost-7.json` | маршрут Mattermost в `TestBuiltinRoutes` |
| `tools/deltas-mattermost-8.json` | `.go-arch-lint.yml`: `mattermost_transport`/`mattermost_wiring` |
| `tools/deltas-mattermost-9.json` | `inamedparam` + удаление `shouldSendTyping`/полей/`websocketReceiveTimeout` |
| `tools/deltas-mattermost-10.json` | удаление `SetTypingThrottleInterval` + `typingMu` + вызов/импорт `time` в `module.go` |
| `tools/deltas-mattermost-11.json` | удаление неиспользуемого импорта `sync` |
| `tools/deltas-mattermost-12.json` | `unlambda`: голое `mattermost.NewAdapter` |
| `tools/deltas-mattermost-13.json` | удаление неиспользуемого импорта `zerolog` из `module.go` |
| `tools/.deltas-state.json` | состояние (sha256 применённых якорей) |
📌 **Дельты 9-13 — это один каскад линтера.** Удаление throttle-механизма тянуло
`SetTypingThrottleInterval` → `typingMu` → `sync` → `zerolog`. Пришлось делать 5 заходов,
каждый раз пересобирая. **Урок: удалять мёртвую фичу одной группой дельт**, а не по одному
симптому — тогда каскад импортов закрывается за раз.
**Формат дельты:**
```json
{ "file": "путь/относительно/корня", "note": "что делаем",