init
This commit is contained in:
@@ -0,0 +1,87 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Что это
|
||||
|
||||
`mcimport` — однобинарный инструмент (Go, только stdlib) для массового создания
|
||||
почтовых ящиков в mailcow из CSV через его REST API. Веб-морда встроена в бинарь
|
||||
(`//go:embed index.html`). Пайплайн пользователя: загрузка CSV → предпросмотр с
|
||||
валидацией → потоковый импорт с журналом.
|
||||
|
||||
## Команды
|
||||
|
||||
```bash
|
||||
# Сборка статического бинаря
|
||||
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o mcimport .
|
||||
|
||||
# Локальный запуск (UI на http://localhost:8080)
|
||||
MAILCOW_URL=https://mail.dom.ru ./mcimport
|
||||
|
||||
# Docker (порт публикуется только на 127.0.0.1 — ходить через SSH-туннель)
|
||||
docker compose up -d --build
|
||||
|
||||
go vet ./...
|
||||
gofmt -l . # список неотформатированных файлов; -w для правки
|
||||
```
|
||||
|
||||
Тестов в проекте нет. `go.mod` не имеет внешних зависимостей — только stdlib,
|
||||
поэтому `go mod tidy`/`go get` при обычной работе не требуются.
|
||||
|
||||
## Архитектура
|
||||
|
||||
Весь backend — один файл `main.go`, весь frontend — один `index.html` (встроен).
|
||||
Состояние на сервере не хранится: инструмент **stateless**, API-ключ и пароли
|
||||
не пишутся на диск и не логируются.
|
||||
|
||||
Четыре HTTP-эндпоинта (`net/http` ServeMux с method-роутингом Go 1.22):
|
||||
|
||||
- `GET /api/config` — отдаёт дефолты в UI (base URL, есть ли ключ в env, дефолт-квота).
|
||||
- `GET /api/example` — отдаёт образец CSV (`exampleCSV`) как вложение для скачивания.
|
||||
- `POST /api/test` — проверка связи: читает домены и ящики, подтверждает ключ и allow-list.
|
||||
- `POST /api/preview` — разбор CSV (multipart), валидация, обогащение против живого mailcow. Form-поле `domain` включает режим override (см. ниже). В ответе — `quotaWarnings` (проверка доменной квоты).
|
||||
- `POST /api/import` — создание ящиков, **потоковый NDJSON** (по строке результата на ящик, с `flusher.Flush()`).
|
||||
|
||||
Три конвейерных этапа обработки строки CSV, каждый меняет `Row.Status`
|
||||
(`create`→`warn`→`exists`→`error`) и флаг `Importable`:
|
||||
|
||||
1. `parseCSV` → `validateRow` — структурная проверка без сети (email, пароль, дубликаты в файле).
|
||||
2. `enrichRow` — сверка с живым mailcow: несуществующий домен → `error`, существующий ящик → `exists` (пропуск). Работает только если заданы креды.
|
||||
3. `checkDomainQuota` — воспроизводит проверку mailcow: свободная квота домена = `max_quota_for_domain` − Σ(выделенных квот существующих ящиков). Если Σ квот импортируемых строк домена превышает свободную — возвращает `quotaWarn` (в МиБ). UI показывает предупреждение и **блокирует** импорт до подъёма квоты домена (домены с квотой 0 = безлимит пропускаются).
|
||||
4. `handleImport` — POST на `/api/v1/add/mailbox`, ответ разбирается `parseMailcowMsg`. Используется **только** `add` — существующие ящики никогда не модифицируются (идемпотентность).
|
||||
|
||||
### Ключевые соглашения
|
||||
|
||||
- **Разрешение кредов** — `resolveCreds`: значения из тела запроса приоритетнее env
|
||||
(`MAILCOW_URL`/`MAILCOW_API_KEY`). Ключ можно задать через env и не вводить в UI.
|
||||
- **Ответы API mailcow** имеют форму `[{"type": "...", "msg": ...}]`; `type != "success"`
|
||||
считается провалом. `msg` бывает строкой или массивом — разворачивается в `flattenMsg`.
|
||||
- **CSV-парсинг** терпимый: авто-определение разделителя (`sniffDelimiter`: `,`/`;`/таб;
|
||||
на практике используется `;`), снятие BOM, `LazyQuotes`, RU-алиасы заголовков
|
||||
(`headerAliases` + `normHeader` игнорирует регистр/пробелы/подчёркивания).
|
||||
`email` можно заменить парой `localpart`+`domain`.
|
||||
- **Режим override-домена** (`parseCSV(..., overrideDomain)`): если домен выбран в UI
|
||||
и передан form-полем `domain`, колонка логина (`email`/`login`/`localpart`)
|
||||
трактуется как localpart без домена, email собирается как `localpart@overrideDomain`.
|
||||
Полный email в значении терпится — берётся часть до `@` с пометкой в `Notes`.
|
||||
Домен нормализуется в lowercase в `handlePreview`.
|
||||
- Ошибки пользователю — **на русском**; комментарии в коде — на английском. Держать этот сплит.
|
||||
- `INSECURE_SKIP_VERIFY=true` отключает проверку TLS (для внутреннего CA mailcow).
|
||||
|
||||
- Дефолт квоты — константа `defaultQuotaMiB` (10240 МиБ). Одна точка правды;
|
||||
дублируется в `docker-compose.yml`, `README.md` и `value` поля `#quota` в `index.html`.
|
||||
- **Единицы квот**: `fetchDomains`/`fetchMailboxes` возвращают квоты в **байтах**
|
||||
(как отдаёт mailcow), `Row.Quota` — в **МиБ** (строка). `checkDomainQuota` сводит
|
||||
всё к байтам, `quotaWarn` наружу — в МиБ. UI форматирует МиБ→ГБ (`gb()`).
|
||||
- **Повтор в UI без перезагрузки файла** (`index.html`): `previewRows`/`importResults`
|
||||
держатся в памяти. «Повторить проверку» = повторный `runPreview()` (файл в `fileInput`
|
||||
сохраняется). «Повторить неудавшиеся» = `runImport()` по строкам с `ok:false` из
|
||||
`importResults` — идемпотентно, т.к. упавшие ящики не создались, успешные не трогаются.
|
||||
|
||||
При добавлении полей ящика править **три места синхронно**: заголовки/алиасы CSV
|
||||
(`headerAliases`), структуру `Row` + `validateRow`, и `payload` в `handleImport`.
|
||||
|
||||
## Требования на стороне mailcow
|
||||
|
||||
- API-ключ с правами **Read-Write** (`Configuration → Access → API`).
|
||||
- IP, с которого ходит mcimport, добавлен в `API_ALLOW_FROM` — иначе отказ доступа (401/403).
|
||||
Reference in New Issue
Block a user