# 1c-audit

Чтение и диагностика базы **1С:Предприятие 8.3** через COM-коннектор.
Библиотека, утилита командной строки и MCP-сервер.

**Только чтение.** Ни расширения конфигурации, ни веб-публикации, ни правки
данных. Доступны `Запрос.Выполнить()` и обход метаданных — и ничего больше.

---

## Зачем, если MCP-серверов для 1С уже много

Их действительно много, но они закрывают другие задачи. Разбор существующих
решений на момент написания:

| Что нужно | Чем это обычно решают | Цена |
|---|---|---|
| Разработка конфигураций: BSL, формы, роли, компиляция | EDT-плагины, BSL Language Server, skills-наборы | бизнес-данных не видят вовсе |
| Данные живой базы | расширение конфигурации | **запись в конфигурацию** |
| Данные живой базы | HTTP-сервис, OData, веб-публикация | публикация базы, инфраструктура |

`1c-audit` занимает пустую клетку: **данные живой базы, ничего не меняя
и ничего не публикуя**. Подключается тем же COM-коннектором, которым
пользуется сама платформа, и работает как с файловой базой, так
и с клиент-серверной.

Это удобно там, где правки в базу вносит человек, а не программа: агент
проходит по базе, ставит диагноз и выдаёт список документов под проверку —
а исправляет их бухгалтер в штатном интерфейсе 1С.

## Что уже проверяет

Шесть проверок, каждая объясняет свой вывод и печатает оговорки рядом
с находкой:

1. **Непроведённые документы** — с детализацией по продажам и проверкой,
   приходили ли деньги.
2. **Обмен с банком** — сообщения в незавершённых статусах, с отсевом
   «сирот» от удалённых и пересозданных платёжек.
3. **Контрагенты** — дубли по ИНН **и КПП**, карточки без ИНН.
4. **Остатки по счетам** — оборотка одной таблицей.
5. **Помеченные на удаление**.
6. **Закрытие месяца** — по каждому завершённому месяцу.

Отчёт заканчивается сводкой «что посмотреть», куда попадает только
устранимое. Принципы отбора — [docs/check-design.md](docs/check-design.md).

## Требования

- Windows: COM-коннектор существует только там
- 1С:Предприятие 8.3 с зарегистрированным `comcntr.dll`
- Python 3.10+, **той же разрядности, что и коннектор** (обычно x64)
- `pywin32`; для MCP-сервера — `mcp`

Регистрация коннектора, разово от администратора:

```
regsvr32 "C:\Program Files\1cv8\<версия>\bin\comcntr.dll"
```

Ошибка «Класс не зарегистрирован» почти всегда означает несовпадение
разрядности, а не отсутствие библиотеки — см.
[docs/com-traps.md](docs/com-traps.md).

## Установка

```
pip install -e .
pip install -e ".[mcp]"    # с MCP-сервером
```

Имя установки и имя импорта различаются:

```
pip install 1c-audit       # дистрибутив — как репозиторий
import onec_audit          # пакет — без цифры в начале
```

Так вышло не из вкусовых предпочтений: идентификатор Python не может
начинаться с цифры, `import 1c_audit` — это `SyntaxError`. `onec` —
устоявшаяся латинизация в питоновской 1С-экосистеме (`onec_dtools`,
`onec-help-mcp`). Расхождение установки и импорта — обычное дело:
`pillow` / `PIL`, `beautifulsoup4` / `bs4`.

## Командная строка

```
onec-audit --base "C:\path\to\base"
onec-audit --base "C:\path\to\base" --locked-before 2025 --out report.txt
onec-audit --srvr SERVER --ref BUH --user Администратор
onec-audit --base "C:\path\to\base" --all-docs
```

Путь можно задать переменной окружения и не повторять:

```
setx ONEC_BASE "C:\path\to\base"
onec-audit
```

**Пароль передавайте только через `ONEC_PWD`.** В аргументах командной строки
он виден всем в списке процессов.

Ключ `--locked-before ГОД` нужен, если в базе установлена дата запрета
изменения: находки в закрытом периоде печатаются с пометкой, но в сводку
не идут — исправить их всё равно нельзя.

## Библиотека

```python
from onec_audit import Base

with Base(r"C:\path\to\base") as b:
    print(b.config_synonym, b.config_version)
    print(b.md.Справочники.Количество(), "справочников")

    for row in b.rows("""
        ВЫБРАТЬ ПЕРВЫЕ 5 Дата, Номер, ПРЕДСТАВЛЕНИЕ(Контрагент) КАК Контрагент
        ИЗ Документ.РеализацияТоваровУслуг
        ГДЕ Проведен И ГОД(Дата) = &Год
        УПОРЯДОЧИТЬ ПО Дата УБЫВ
    """, Год=2025):
        print(row.Дата, row.Номер, row.Контрагент)
```

Два правила, которые сэкономят вам день отладки:

- **Даты не передавайте параметрами** — сдвигаются на часовой пояс.
  Используйте `ГОД()`/`МЕСЯЦ()` целыми или `datetime_literal()`.
- **Текст ссылок и перечислений берите в запросе** — `ПРЕДСТАВЛЕНИЕ(...)`
  или `.Код`, а не приведением на стороне Python.

Почему именно так — [docs/com-traps.md](docs/com-traps.md).

## MCP-сервер

Четыре инструмента, все read-only: `query`, `list_metadata`, `describe`,
`row_counts`.

```json
{
  "mcpServers": {
    "1c-audit": {
      "command": "python",
      "args": ["-m", "onec_audit.mcp_server"],
      "env": { "ONEC_BASE": "C:\\path\\to\\base" }
    }
  }
}
```

`list_metadata` и `describe` существуют не для красоты: **угадывание имён
метаданных — главный источник ошибок**. Имя перечисления или реквизита
почти никогда не то, которое кажется очевидным.

## Документация

- [docs/com-traps.md](docs/com-traps.md) — пять граблей COM-доступа к 1С,
  три в PowerShell и две в Python. Все тихие: исключения нет, просто данные
  неверные.
- [docs/check-design.md](docs/check-design.md) — как проектировать проверки,
  чтобы сводке верили. С примерами признаков, которые давали ложные
  срабатывания, и того, чем их заменили.

## Границы

Осознанно не делает и делать не будет:

- не пишет в базу и не проводит документы;
- не меняет конфигурацию и не требует расширений;
- не разбирает формат `.1CD` — только штатный COM-коннектор;
- не решает за бухгалтера. Вывод — список документов под проверку,
  решение и правка остаются за человеком.

## Лицензия

MIT.