[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:
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": "что делаем",
|
||||
|
||||
Reference in new issue
Block a user