cdc-1c 0.1.0__tar.gz

cdc_1c-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      # integration-тесты (живая 1С/Postgres) отсеиваются addopts из pyproject.
+      - run: uv run pytest -q
+
+  publish:
+    # Публикация на PyPI по git-тегу vX.Y.Z. Требует настроенного Trusted Publishing на стороне PyPI
+    # (проект + этот репозиторий/workflow) — секреты/токены не нужны.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish --trusted-publishing always

cdc_1c-0.1.0/.gitignore

@@ -0,0 +1,215 @@
+# Claude Code local settings
+.claude/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+
+
+.vscode
+.qwen
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

cdc_1c-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/),
+версионирование — [SemVer](https://semver.org/lang/ru/).
+
+## [0.1.0] — Unreleased
+
+Первый публичный релиз (Development Status :: Alpha).
+
+### Added
+- Оркестратор `Replicator1C`: чтение изменений из 1С (OData + план обмена) и upsert в целевую БД
+  через `dbmerge`; подтверждение приёма пакета только после успешного сохранения (`run_once` /
+  `run_forever` с graceful SIGTERM/SIGINT).
+- Полная выгрузка `full_load`: keyset-пагинация (Ref_Key / Recorder / составной ключ независимого
+  регистра), фильтр по периоду (`date_field` + `date_from`/`date_to`), фоновые выгрузки в
+  `run_forever`.
+- Version-guard полной выгрузки (`exchange_message_no`): устаревший снимок не затирает более свежие
+  изменения и не воскрешает удалённые строки групп (регистр/табличная часть).
+- Транслитерация имён и лимиты идентификаторов (`NameMapper1C`); спец-поля `merged_on`,
+  `inserted_on`, `is_deleted_or_empty`, `exchange_message_no`.
+- Служебные таблицы: журнал загрузок `replicator_1c_log`, реестр объектов `metadata_objects_1c`.
+
+[0.1.0]: https://github.com/pavel-v-sobolev/cdc_1C/releases/tag/v0.1.0

cdc_1c-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pavel Sobolev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cdc_1c-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: cdc-1c
+Version: 0.1.0
+Summary: Change data capture (CDC) from 1C:Enterprise to your data warehouse
+Project-URL: Homepage, https://github.com/pavel-v-sobolev/cdc_1C
+Project-URL: Repository, https://github.com/pavel-v-sobolev/cdc_1C
+Project-URL: Issues, https://github.com/pavel-v-sobolev/cdc_1C/issues
+Author-email: Pavel Sobolev <pavel-v-sobolev@yandex.ru>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 1c,1c-enterprise,cdc,data-engineering,dwh,etl,postgres,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: dbmerge>=1.0.20
+Requires-Dist: requests>=2.33.0
+Requires-Dist: sqlalchemy>=2.0.49
+Requires-Dist: xmltodict>=1.0.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9.12; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+**cdc-1c** is a docker container and a Python library, that provides 1C system data loading to data warehouse using Change Data Capture apporach. \
+It engages standard ODATA mechanism and standard 1C exchange plan mechanism to extract data from 1C system and upsert changes to the target DB.
+
+**cdc-1c** - это докер контейнер и python-библиотека, предназначенные для получения данных из 1С, использующий подход CDC (загрузка изменений данных). \
+Продукт использует стандартный интерфейс ODATA и механизм планов обмена для выгрузки изменений данных из системы 1С и обновления данных в целевой БД.
+
+# Что нужно для работы
+1) опубликовать базу 1с на web
+2) создать пользователя odata и дать ему необходимые права
+3) настроить план обмена в конфигураторе и включить в его состав нужные объекты 1с
+3) настроить узел обмена с использованием внешней обработки `cdc-1c.odt`
+4) поднять docker контейнер (плока не доступен - todo) для получения данных или адаптировать под свой вариант, исспользуя библиотеку python cdc-1c
+
+# Использование библиотеки python
+
+Библиотека даёт оркестратор `Replicator1C`, который читает изменения из 1С (OData + план обмена) и
+складывает их в целевую БД, подтверждая приём пакета только после успешного сохранения. БД
+передаётся готовым SQLAlchemy `engine`.
+
+## Установка
+
+```bash
+pip install cdc-1c
+
+# c драйвером PostgreSQL (тестовая СУБД):
+pip install "cdc-1c[postgres]"
+```
+
+Поддерживается Python 3.10+. Модуль тестировался на PostgreSQL, но целевой может быть любая БД из
+числа поддерживаемых модулем `dbmerge` (через него идёт запись). Сама библиотека драйвер БД не
+импортирует — его ставите под свою СУБД (для PostgreSQL — extra `[postgres]` выше).
+
+## Быстрый старт
+
+```python
+from sqlalchemy import create_engine
+from cdc_1c import Replicator1C
+
+engine = create_engine("postgresql+psycopg2://user:pass@localhost:5432/dwh", pool_size=5)
+
+rep = Replicator1C(
+    odata_url="http://host/base/odata/standard.odata",
+    odata_auth=("odata", "secret"),        # (user, password) либо None без авторизации
+    exchange_name="ДляODATA",              # имя плана обмена в 1С
+    queue_guid="a9bc23c5-3689-11f1-926c-0800270bc6cb",  # Ref_Key узла обмена (очереди)
+    engine=engine,
+    db_schema="cdc_1c",                    # None → схема БД по умолчанию (public у Postgres)
+    request_timeout=60,                    # таймаут HTTP-запросов к 1С, сек (по умолчанию = interval)
+    full_load_workers=2,                   # число фоновых потоков полной выгрузки
+)
+
+rep.run_forever(interval=60)               # цикл опроса раз в 60 секунд
+```
+
+
+## Режимы: `run_once` и `run_forever`
+
+```python
+rep.run_once()                 # один цикл: read → save → notify (подтверждение только после save)
+rep.run_forever(interval=60)   # бесконечный цикл run_once с паузой; фоном — полные выгрузки
+```
+
+- `run_once(notify_changes=False)` — не подтверждать приём (пакет останется в очереди 1С; сделано для отладки).
+- `run_forever(interval, max_iterations=0)` — `max_iterations>0` ограничивает число итераций.
+
+## Полная (первоначальная) выгрузка
+
+При работе `run_forever` объекты, впервые встреченные в пакете изменений, автоматически ставятся в
+очередь на полную выгрузку и грузятся фоновыми потоками. Можно запустить выгрузку и вручную:
+
+Полная выгрузка объекта реализована на стороне python, чтобы поддержать выгрузку объектов больших размеров, 
+т.к. если инициировать полную выгрузку по плану обмена в 1С, то данные поступят без возможности постраничной загрузки.
+(Поэтому данная функция специально убрана из модуля 1С).
+
+Полная выгрузка спроектирована так, чтобы работать параллельно с получением изменений объекта.
+
+```python
+rep.list_objects()             # имена объектов 1С, доступных для выгрузки (Catalog_…, Document_…, …)
+
+rep.full_load("Catalog_Номенклатура")              
+rep.full_load("Document_РеализацияТоваровУслуг", batch_size=500)
+```
+
+
+### Фильтр по периоду
+
+Для ручной догрузки за нужный период укажите поле даты/времени и границы (включительно):
+
+```python
+from datetime import date, datetime
+
+# весь месяц: date-граница включает последний день целиком (даже для поля дата-время)
+rep.full_load("Document_РеализацияТоваровУслуг",
+              date_field="Date", date_from=date(2026, 6, 1), date_to=date(2026, 6, 30))
+
+# точная граница по времени — передайте datetime
+rep.full_load("Document_РеализацияТоваровУслуг",
+              date_field="Date", date_from=datetime(2026, 6, 1, 9, 0, 0))
+```
+
+`date_field` — имя поля 1С (`Date` у документов, `Period` у регистров). Границы транслируются в OData
+`$filter` и объединяются с курсором пагинации.
+
+## Что появляется в целевой БД
+
+- На каждый объект 1С — таблица (имя транслитерируется, длинные имена усекаются с хэшем под лимит СУБД).
+- Служебные поля строк: `merged_on`/`inserted_on` (момент merge/первой вставки), `is_deleted_or_empty`
+  (пометка удаления/пустой набор), `exchange_message_no` (номер пакета обмена).
+- Служебные таблицы `replicator_1c_log` и `metadata_objects_1c` (см. ниже).
+
+## Служебные таблицы
+
+### `replicator_1c_log` — журнал загрузок
+
+Строка на каждую загрузку объекта: пакет изменений или полная выгрузка.
+
+| Колонка | Назначение |
+|---|---|
+| `id` | суррогатный ключ |
+| `exchange` | имя плана обмена |
+| `object` | имя объекта 1С |
+| `type` | `changes` (пакет изменений) или `full` (полная выгрузка) |
+| `message_no` | номер пакета обмена; `NULL` для полной выгрузки |
+| `started_at` / `finished_at` | начало и конец загрузки; `finished_at IS NULL` — не завершена (упала) |
+| `inserted_row_count` / `updated_row_count` / `deleted_row_count` | счётчики строк merge |
+| `total_time` | суммарное время merge, сек |
+
+Предназначено для мониторинга: незавершённые строки (`finished_at IS NULL`) — упавшие загрузки; по `type` и
+`object` видно, что и когда грузилось.
+
+### `metadata_objects_1c` — реестр объектов и состояние полной выгрузки
+
+Синхронизируется с метаданными 1С — строка на каждый объект, встреченный в обмене. Ключ таблицы — полное
+имя объекта (регистр и документ могут иметь одинаковое короткое имя).
+
+| Колонка | Назначение |
+|---|---|
+| `object_full_name` | полное имя объекта 1С (ключ), например `Catalog_Номенклатура` |
+| `object_full_name_en` | транслит = имя таблицы объекта в БД |
+| `object_name` / `object_type` | имя и тип объекта (`Catalog` / `Document` / `AccumulationRegister` / …) |
+| `fields` / `fields_en` | список полей объекта: имена 1С и их транслит (= колонки в БД) |
+| `full_load_is_required` | объект ожидает полной выгрузки |
+| `last_full_load_dt` | когда объект был полностью выгружен; `NULL` — ни разу |
+| `merged_on` | момент синхронизации записи реестра |
+
+Новый объект оркестратор помечает `full_load_is_required=true`, фоновый воркер выгружает его целиком и
+проставляет `last_full_load_dt`. Отсюда же удобно посмотреть список доступных объектов и имена их таблиц.
+
+## Логирование
+
+Из коробки библиотека вешает вывод на логгер `cdc_1c` (INFO), если приложение не настроило логирование
+само. Настроили своё — библиотека молчит и пишет через стандартный `logging`.
+
+## Дальнейшая материализация и сборка денормализованных таблиц
+
+1С хранит данные в нормализованном виде. Это значит, что чтобы дотянуться, например, 
+из регистра заказов до кода товара, нужно делать JOIN с таблицей номенклатуры по идентификатору товара в виде guid.
+В тоже время для задач DWH часто нужны данные с менее строгой нормализацией. 
+Поэтому тут предложены примеры кода, как сделать инкрементное обновление последующей целевой таблицы с денормализованными данными:
+
+[Вариант с сохранением guid ключа в таблице фактов](https://github.com/pavel-v-sobolev/cdc-1c/blob/main/materialize_example.py)
+[Вариант с изменение ключа, использующий GROUP BY, но все равно оптимизированный и инкрементный](https://github.com/pavel-v-sobolev/cdc-1c/blob/main/materialize_example_other_key.py)
+

cdc_1c-0.1.0/PLAN.md

@@ -0,0 +1,124 @@
+# План проекта cdc-1c
+
+## Context
+
+Ядро CDC из 1С (OData → БД через dbmerge) реализовано и проверено на живой 1С + PostgreSQL:
+чтение изменений (`ChangeReader1C`), разбор в колоночные `DataObject1C`, транслитерация и лимиты
+имён (`NameMapper1C`), типы/ключи/`delete_key` из метаданных (`MetadataReader1C`), пер-объектное
+сохранение со scoped-delete для регистров/ТЧ (`DBWriter1C`), спец-поля `is_deleted_or_empty` и
+`exchange_message_no`.
+
+Текущая цель: оформить наработку как opensource-продукт — Python-пакет на PyPI + Docker-образ для
+запуска «из коробки» с минимумом настроек, и удобный оркестратор с простым вызовом.
+
+## Решения
+- Имя: дистрибутив **cdc-1c**, import-пакет **cdc_1c** (нижний регистр); классы PascalCase.
+- Оркестратор: класс **`Replicator1C`** (суффикс `1C` — как у остальных публичных классов).
+- Конструктор: **отдельные именованные аргументы** (не объект `Config`) — прямой библиотечный
+  вызов без обёртки, единый стиль с прочими классами. БД передаётся готовым **`engine`** (DI по-
+  sqlalchemy'ному, тестируемость, переиспользование), а не строкой; тот же engine идёт в `DBWriter1C`.
+- `Config` (dataclass) — env-сторона: хранит `db_url`; classmethod **`Replicator1C.from_config(cfg)`**
+  строит engine из `db_url` (граница «строка → engine» в одном месте) и маппит поля. `poll_interval`/
+  `log_level` остаются в `Config` для `run_forever`/логирования. Entrypoint: `Config.from_env()`.
+- Режимы оркестратора: `run_once()` и `run_forever(interval)`.
+- Python: **>=3.10**. Лицензия: **MIT** (предварительно).
+
+---
+
+## Сделано (ядро CDC)
+
+- **`_get_register_records` / удаление наборов** — `_default_key_value`, `_make_deleted_register_record`:
+  при пустом `RecordSet` запись дополняется полным ключом из метаданных (дефолты) + реальные
+  `Recorder`/`Recorder_Type`.
+- **`NameMapper1C`** — транслитерация; лимит `POSTGRES_MAX_IDENTIFIER = 63` (обрезка + 4-симв. хэш);
+  служебные имена `RESERVED_FIELD_NAMES` (`merged_on`, `inserted_on`, `exchange_message_no`): наше
+  служебное поле сохраняет имя, поле 1С с таким же транслитом хэшируется; журнал
+  `object_mappings`/`field_mappings`. Ручной маппинг убран.
+- **`DataReader1C`** — `DataObject1C.to_records_mapped()` (dict-of-lists → list-of-dict, маппинг
+  колонок на лету, без копии); `_convert_value` для `Guid` → `uuid.UUID`.
+- **`DBWriter1C`** — пер-объектное сохранение; удаление по `metadata_obj.delete_key`: документ/
+  справочник → `delete_mode='no'`; регистр/ТЧ → `delete_mode='delete'` со scoped `delete_condition`
+  (`_scoped_delete_condition`: подзапрос из temp-таблицы — `col IN (SELECT col FROM temp)` или
+  row-value `tuple_(...).in_(select(...))`). `Config`/`data_reader` в конструкторе, `save_all()`.
+- **`MetadataReader1C`** — `MetadataObject1C.delete_key` + `_get_delete_key` (регистр →
+  `Recorder`/`Recorder_Type`; ТЧ → `Ref_Key`; документ/справочник → None).
+- **Табличные части** — строкам ТЧ проставляется `Ref_Key` владельца (в данных 1С его нет);
+  пустая ТЧ → фиктивная запись (`_make_empty_table_part_record`) для scoped-delete по `Ref_Key`.
+- **Спец-поля** — `is_deleted_or_empty` (Boolean: `DeletionMark` документа/справочника, проброс
+  пометки в строки ТЧ, `True` у фиктивных записей) и `exchange_message_no` (номер пакета обмена,
+  во всех записях; ставится в `ChangeReader.read_changes`).
+- **A1. Переименование** — `src/cdc_1C` → `src/cdc_1c`, все импорты `cdc_1C` → `cdc_1c`,
+  `pyproject` `name = "cdc-1c"`, `version("cdc-1c")`. Пересобрано `uv sync` (cdc-1c==0.1.0).
+
+---
+
+## Осталось
+
+### Фаза A. Hardening ядра
+- **A2. Конфигурируемый auth** — ✅ (частично) `MetadataReader1C`/`DataReader1C.__init__` принимают
+  `auth: tuple[str,str] | None`, хранят `self.auth`; все `requests.*` используют `auth=self.auth`;
+  `ChangeReader1C` пробрасывает `auth`. Захардкоженные `('admin','admin')` убраны (4 места).
+  Осталось: общий `requests.Session`, `timeout`, опц. `verify`.
+- **A3. Сброс состояния** — ✅ `ChangeReader1C.read_changes()` в начале делает `self.clear()`.
+- **A4. `Config` (dataclass)** — ✅ (частично) `src/cdc_1c/config.py`: `odata_url`, `odata_user`,
+  `odata_password`, `exchange_name`, `queue_guid`, `db_url`, `db_schema`, `poll_interval`, `log_level`;
+  `from_env()` читает `CDC1C_*`. Осталось: опц. `request_timeout`, `verify_ssl` (вместе с остатком A2).
+- **A5. Оркестратор `Replicator1C`** — ✅ `src/cdc_1c/replicator.py`: собирает
+  metadata/changes/mapper/writer из отдельных аргументов (engine + auth из user/password); classmethod
+  `from_config(Config)` строит engine из `db_url`; `run_once()` (read → save → **notify только после
+  успешного save**); `run_forever(interval)` с обработкой исключений (упал цикл → лог, без notify,
+  повтор) и graceful SIGTERM/SIGINT (`_StopSignal`). Экспортирован из `cdc_1c`.
+- **A6. Логирование** — ✅ во всех модулях `logger = logging.getLogger(__name__)`, `basicConfig()`/root
+  убраны (ридеры/writer/replicator/config). Авто-вывод из коробки — `src/cdc_1c/logging_config.py`
+  `_ensure_handler()` (вешает StreamHandler на логгер `cdc_1c` с INFO, только если `hasHandlers()` ==
+  False), вызывается из `Replicator1C.__init__`. Если приложение настроило логирование — молчим.
+  Уровень из `Config.log_level` — настраивать в entrypoint (B2). Проверено: на чистом root INFO виден
+  из коробки, при настроенном приложением логировании — молчим. Зависимость **dbmerge** переведена на
+  тот же паттерн (`getLogger('dbmerge')` + `hasHandlers()`, без `basicConfig`) — root больше не
+  загрязняется, обе библиотеки сосуществуют чисто.
+- ✅ Файлы модулей в snake_case (`metadata_reader.py`, `data_reader.py`, `change_reader.py`,
+  `name_mapper.py`, `db_writer.py`); классы и реэкспорт из `__init__` не изменены, публичный API
+  (`from cdc_1c import …`) прежний.
+
+### Фаза B. Упаковка для PyPI
+- **B1. `pyproject.toml`** — описание, `license = "MIT"`, авторы, `requires-python = ">=3.10"`,
+  keywords/classifiers/urls; ядро: `dbmerge`, `requests`, `sqlalchemy`, `xmltodict` (убрать `polars`
+  и `psycopg2` из обязательных); `[project.optional-dependencies] postgres = ["psycopg[binary]>=3.2"]`
+  (psycopg3, DSN `postgresql+psycopg`); `[project.scripts] cdc-1c = "cdc_1c.__main__:main"`.
+- **B2. Entrypoint** — `src/cdc_1c/__main__.py`: `Config.from_env()` → `Replicator`; режим
+  `CDC1C_MODE=once|loop` (по умолчанию loop). Работает как `python -m cdc_1c` и команда `cdc-1c`.
+- **B3.** `LICENSE`, `src/cdc_1c/py.typed`, `CHANGELOG.md`; английский README (quickstart pip+Docker,
+  таблица ENV, требования к плану обмена OData в 1С, поведение имён, спец-поля, ограничения);
+  `main.py` → краткий пример использования `Replicator` (или удалить).
+
+### Фаза C. Docker «из коробки»
+- **C1. `Dockerfile`** — `python:3.12-slim`, `cdc-1c[postgres]`, `ENTRYPOINT ["cdc-1c"]`, ENV,
+  graceful SIGTERM.
+- **C2. `docker-compose.yml`** — сервис `cdc-1c` + опциональный `postgres`; `.env.example`;
+  README-раздел «Запуск в Docker за 1 минуту».
+
+### Фаза D. Качество
+- **D1. Тесты (pytest)** — `NameMapper1C`, `to_records_mapped`, `_get_delete_key`; на sqlite —
+  `DBWriter1C` scoped-delete (регистр/ТЧ/пустая ТЧ), идемпотентность, фиктивные записи,
+  `is_deleted_or_empty` по всем веткам, GUID→`uuid.UUID`; ридеры — фикстуры реального XML
+  `SelectChanges`/`$metadata`.
+- **D2. CI (GitHub Actions)** — ruff, тесты на матрице 3.10–3.13, сборка; публикация на PyPI по
+  git-тегу (OIDC/trusted publishing).
+
+---
+
+## Известные ограничения (→ README)
+- Фиктивные записи (удалённый набор регистра, пустая ТЧ) вставляются как заглушка с дефолтным
+  ключом (`LineNumber=0`); реальные старые строки удаляются scoped-delete'ом. Отличаются по
+  `is_deleted_or_empty=True`.
+- Опустевшая ТЧ как `xsi:nil` сейчас отфильтровывается (`_get_record_table_parts`) — уточнить формат
+  1С и допокрыть при необходимости.
+- Уникальность обрезанных длинных имён строго не гарантируется (хэш от полного имени).
+
+## Проверка (end-to-end)
+1. `uv sync`; `pytest` — зелёные offline-тесты (без 1С/Postgres).
+2. `Config(...)` → `Replicator(cfg).run_once()` против живой 1С + Postgres: таблицы, типы,
+   scoped-delete, спец-поля; повторный прогон — идемпотентность.
+3. `run_forever(interval=…)`: цикл чистит состояние, notify только после успешного save, реакция на SIGTERM.
+4. Docker: `docker compose up` с заполненным `.env` → данные грузятся без правок кода; `docker stop` штатно завершает.
+5. `uv build` + установка из wheel в чистом окружении (3.10): импорт и `cdc-1c`/`python -m cdc_1c`.