mesilov · mesilov · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 /.idea*
+.DS_Store
 /vendor
 /.cache
 /docker/db
@@ -7,4 +8,4 @@ composer.lock
 .phpunit.result.cache
 *.log
 .env.local
-*.cache
+*.cache
diff --git a/.mcp.json b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "bitrix24-dev": {
+      "type": "http",
+      "url": "https://mcp-dev.bitrix24.tech/mcp"
+    }
+  }
+}
diff --git a/.tasks/90/developer-docs-update-plan.md b/.tasks/90/developer-docs-update-plan.md
diff --git a/.tasks/90/install-handler-status-fix-plan.md b/.tasks/90/install-handler-status-fix-plan.md
diff --git a/.tasks/93/table-names-normalization-plan.md b/.tasks/93/table-names-normalization-plan.md
@@ -0,0 +1,70 @@
+## План по issue #93: нормализация Doctrine-таблиц (`b24lib_` + plural)
+
+### Summary
+Нужно унифицировать имена всех Doctrine-таблиц библиотеки и явно именованных schema-объектов, чтобы они:
+- имели префикс `b24lib_`
+- использовали множественное число для таблиц сущностей
+
+Целевое переименование:
+- `application_installation` -> `b24lib_application_installations`
+- `application_settings` -> `b24lib_application_settings`
+- `bitrix24account` -> `b24lib_bitrix24_accounts`
+- `contact_person` -> `b24lib_contact_persons`
+
+Работа ограничивается обновлением маппингов, тестов и документации внутри библиотеки. Встроенная миграция существующих БД в самой библиотеке в scope не входит, но upgrade path должен быть явно описан в `CHANGELOG.md` как breaking change.
+
+### Important Interface Changes
+Публичные PHP API, сигнатуры классов и repository-интерфейсы не меняются.
+
+Меняются только инфраструктурные имена Doctrine schema-объектов:
+- XML mapping `table="..."`
+- имена `indexes`, `unique-constraints` и других явно именованных DB-объектов в mappings
+- ожидания в functional/tests и schema assertions
+- документация и changelog, где старые таблицы названы явно
+
+### Implementation Changes
+1. Обновить Doctrine XML mappings в `config/xml`, заменив имена таблиц на новые `b24lib_*`.
+2. Не менять имена колонок, foreign key columns, embedded mappings и доменные имена сущностей.
+3. Переименовать все явно заданные schema-объекты в mappings так, чтобы они были консистентны с новой схемой и использовали `b24lib_`-нейминг:
+- `unique_app_setting_scope` -> `b24lib_application_settings_unique_scope`
+- `idx_application_installation_id` -> `b24lib_application_settings_idx_application_installation_id`
+- `idx_b24_user_id` -> `b24lib_application_settings_idx_b24_user_id`
+- `idx_b24_department_id` -> `b24lib_application_settings_idx_b24_department_id`
+- `idx_key` -> `b24lib_application_settings_idx_key`
+- `idx_status` -> `b24lib_application_settings_idx_status`
+- если в затронутых mappings обнаружатся другие явно именованные schema-объекты, их привести к тому же правилу: `b24lib_<table>_<object-purpose>`
+4. Не добавлять migration runner, console command или встроенный SQL helper: breaking change сопровождается документированным ручным апгрейдом через `CHANGELOG.md`, а не автоматическим апгрейдом внутри библиотеки.
+5. Обновить тесты, которые опираются на фактическую схему Doctrine/PostgreSQL:
+- проверки через `schema-tool:create` / `schema-tool:update --dump-sql`
+- любые assertions или fixture-логика, где фигурируют старые table names
+- при наличии явных schema assertions добавить проверку новых имен таблиц и явно именованных индексов/constraints
+- smoke на introspection/truncate, чтобы работа со схемой не зависела от старых имен
+6. Обновить документацию:
+- `CHANGELOG.md` в секции `Unreleased 0.5.0` добавить отдельный `BC`/`Breaking Changes` блок с upgrade note для существующих установок
+- в upgrade note перечислить все переименования `old -> new` для таблиц и явно именованных schema-объектов и явно указать, что перед обновлением потребитель должен переименовать существующие объекты схемы вручную
+- `src/ApplicationSettings/Docs/application-settings.md` и другие места, где таблицы названы текстом
+7. Не трогать строки исключений и доменные сообщения вида `bitrix24account not found`, если они описывают сущность, а не SQL-таблицу.
+
+### Test Cases and Scenarios
+1. `make test-functional`
+- схема успешно дропается и создается через Doctrine с новыми table names
+- `orm:schema-tool:update --dump-sql` не предлагает лишних изменений после `create`
+- functional test suite остается зеленым
+
+2. `make test-unit`
+- unit suite остается зеленым как регрессия после изменения mapping metadata и docs-сопровождения
+
+3. Ручная schema-проверка в рамках functional bootstrap
+- в БД присутствуют только новые таблицы `b24lib_*`
+- явно именованные индексы и unique constraints используют новый `b24lib_*`-нейминг
+- старые имена не появляются в generated schema
+
+4. Документационная проверка
+- в `CHANGELOG.md` есть отдельный `BC`/upgrade note с полным списком переименований таблиц и явно именованных schema-объектов
+- в пользовательской документации не осталось старых таблиц как актуальных
+
+### Assumptions and Defaults
+- Источник истины по схеме: Doctrine XML mappings в `config/xml`.
+- Scope изменения: меняются table names и явно именованные schema-объекты; column names и семантика связей не переименовываются.
+- Breaking change допустим для milestone `0.5.0` и должен быть явно отмечен в changelog.
+- Для существующих установок библиотека не поставляет автоматический migration path; потребитель выполняет ручное переименование таблиц и других затронутых schema-объектов по инструкции из `CHANGELOG.md`.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,30 @@
+# AGENTS
+
+## MCP Servers
+
+This repository includes project-level MCP server configuration in `.mcp.json`.
+
+Developers and agents working with this project must verify the MCP configuration before starting work.
+
+Configured servers:
+
+- `bitrix24-dev` - HTTP MCP server at `https://mcp-dev.bitrix24.tech/mcp`
+
+Checks before work starts:
+
+- ensure `.mcp.json` is present and contains the expected server list
+- restart the client after pulling changes to `.mcp.json`
+- verify that the configured MCP servers are available in the current client
+
+## Tests And Linters
+
+Agents working in this repository must run linters and tests only through `Makefile` entrypoints.
+
+Do not call tool binaries directly when an equivalent `make` target exists.
+
+Use:
+
+- `make lint-all` for the full linter pass
+- `make test-unit` for the unit test suite
+- `make test-functional` for the functional test suite
+- `make lint-cs-fixer-fix` and `make lint-rector-fix` only when an autofix pass is needed
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,41 @@
-## Unreleased
+## Unreleased 0.5.0
+
+### BC
+- Normalize Doctrine table names for library-owned storage and align explicit schema object names [#93](https://github.com/mesilov/bitrix24-php-lib/issues/93)
+    - Tables renamed:
+        - `application_installation` -> `b24lib_application_installations`
+        - `application_settings` -> `b24lib_application_settings`
+        - `bitrix24account` -> `b24lib_bitrix24_accounts`
+        - `contact_person` -> `b24lib_contact_persons`
+    - Explicit schema object names renamed for `b24lib_application_settings`:
+        - `unique_app_setting_scope` -> `b24lib_application_settings_unique_scope`
+        - `idx_application_installation_id` -> `b24lib_application_settings_idx_application_installation_id`
+        - `idx_b24_user_id` -> `b24lib_application_settings_idx_b24_user_id`
+        - `idx_b24_department_id` -> `b24lib_application_settings_idx_b24_department_id`
+        - `idx_key` -> `b24lib_application_settings_idx_key`
+        - `idx_status` -> `b24lib_application_settings_idx_status`
+    - Upgrade note for existing PostgreSQL installations:
+        - Before the first run on `0.5.0`, rename existing tables and explicitly named indexes manually.
+        - Example SQL:
+```sql
+ALTER TABLE application_installation RENAME TO b24lib_application_installations;
+ALTER TABLE application_settings RENAME TO b24lib_application_settings;
+ALTER TABLE bitrix24account RENAME TO b24lib_bitrix24_accounts;
+ALTER TABLE contact_person RENAME TO b24lib_contact_persons;
+
+ALTER INDEX unique_app_setting_scope RENAME TO b24lib_application_settings_unique_scope;
+ALTER INDEX idx_application_installation_id RENAME TO b24lib_application_settings_idx_application_installation_id;
+ALTER INDEX idx_b24_user_id RENAME TO b24lib_application_settings_idx_b24_user_id;
+ALTER INDEX idx_b24_department_id RENAME TO b24lib_application_settings_idx_b24_department_id;
+ALTER INDEX idx_key RENAME TO b24lib_application_settings_idx_key;
+ALTER INDEX idx_status RENAME TO b24lib_application_settings_idx_status;
+```
+
+### Fixed
+- Fix start state for Bitrix24 ApplicationAccounts and ApplicationInstall [#90](https://github.com/mesilov/bitrix24-php-lib/issues/90)
+
+
+
 
 ## 0.4.0
 

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -119,6 +119,13 @@ src/
 ## Environment Variables
 Located in `.env` and `.env.local` files for database configuration.
 
+## MCP Servers
+- Project-level MCP configuration is stored in `.mcp.json`.
+- Developers using Claude Code or Codex must verify the MCP configuration before starting work in this repository.
+- Configured servers:
+  - `bitrix24-dev` - HTTP MCP server at `https://mcp-dev.bitrix24.tech/mcp`
+- If `.mcp.json` changes, restart the client so the updated project MCP configuration is reloaded.
+
 ### Default Configuration for Functional Tests
 The `.env` file contains default values that work out-of-the-box with Docker Compose:
 - `DATABASE_HOST=database` (Docker service name)
@@ -128,4 +135,4 @@ The `.env` file contains default values that work out-of-the-box with Docker Com
 - `POSTGRES_VERSION=16`
 
 These defaults allow running functional tests immediately after `make up` without additional configuration.
-- Always update changelog.md
+- Always update changelog.md
diff --git a/Makefile b/Makefile
@@ -157,7 +157,7 @@ debug-show-env:
 
 .PHONY: test-functional
 test-functional: debug-show-env
-	docker compose run --rm php-cli php bin/doctrine orm:schema-tool:drop --force
+	docker compose run --rm php-cli php bin/doctrine orm:schema-tool:drop --force --full-database
 	docker compose run --rm php-cli php bin/doctrine orm:schema-tool:create
 	docker compose run --rm php-cli php bin/doctrine orm:schema-tool:update --dump-sql
 	docker compose run --rm php-cli php vendor/bin/phpunit --testsuite=functional_tests --display-warnings --testdox
@@ -168,7 +168,7 @@ test-functional-one: debug-show-env
 
 .PHONY: doctrine-schema-drop
 doctrine-schema-drop:
-	docker compose run --rm php-cli php bin/doctrine orm:schema-tool:drop --force
+	docker compose run --rm php-cli php bin/doctrine orm:schema-tool:drop --force --full-database
 
 .PHONY: doctrine-schema-create
 doctrine-schema-create:

diff --git a/README.md b/README.md
@@ -92,6 +92,22 @@ src/
 - Docker and Docker Compose
 - Make
 
+### MCP Servers
+
+The project contains project-level MCP server configuration in `.mcp.json`.
+
+Developers using Claude Code or Codex must verify the MCP configuration before starting work on the repository.
+
+Configured servers:
+
+- `bitrix24-dev` - HTTP MCP server at `https://mcp-dev.bitrix24.tech/mcp`
+
+Recommended checks:
+
+- ensure `.mcp.json` is present and contains the expected server list
+- restart the client after pulling changes to `.mcp.json`
+- verify server availability in the client before work starts
+
 ### Running Tests
 
 ```bash
@@ -128,4 +144,4 @@ No additional configuration needed for running tests.
 2. Library is covered with tests
 3. All work is organized through issues
 4. Development processes are remote first
-5. Think and discuss — then write
+5. Think and discuss — then write
diff --git a/config/xml/Bitrix24.Lib.ApplicationInstallations.Entity.ApplicationInstallation.dcm.xml b/config/xml/Bitrix24.Lib.ApplicationInstallations.Entity.ApplicationInstallation.dcm.xml
@@ -2,7 +2,7 @@
                   xmlns:xs="https://www.w3.org/2001/XMLSchema"
                   xmlns:orm="https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
     <entity name="Bitrix24\Lib\ApplicationInstallations\Entity\ApplicationInstallation"
-            table="application_installation">
+            table="b24lib_application_installations">
         <id name="id" type="uuid" column="id">
 
         </id>
@@ -35,4 +35,4 @@
 
         <embedded name="applicationStatus" class="Bitrix24\SDK\Application\ApplicationStatus"/>
     </entity>
-</doctrine-mapping>
+</doctrine-mapping>
diff --git a/config/xml/Bitrix24.Lib.ApplicationSettings.Entity.ApplicationSettingsItem.dcm.xml b/config/xml/Bitrix24.Lib.ApplicationSettings.Entity.ApplicationSettingsItem.dcm.xml
@@ -2,7 +2,7 @@
                   xmlns:xs="https://www.w3.org/2001/XMLSchema"
                   xmlns:orm="https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
     <entity name="Bitrix24\Lib\ApplicationSettings\Entity\ApplicationSettingsItem"
-            table="application_settings">
+            table="b24lib_application_settings">
         <id name="id" type="uuid" column="id">
 
         </id>
@@ -28,15 +28,15 @@
         <field name="updatedAt" type="carbon_immutable" column="updated_at_utc" precision="3" nullable="false"/>
 
         <unique-constraints>
-            <unique-constraint columns="application_installation_id,key,b24_user_id,b24_department_id" name="unique_app_setting_scope"/>
+            <unique-constraint columns="application_installation_id,key,b24_user_id,b24_department_id" name="b24lib_application_settings_unique_scope"/>
         </unique-constraints>
 
         <indexes>
-            <index name="idx_application_installation_id" columns="application_installation_id"/>
-            <index name="idx_b24_user_id" columns="b24_user_id"/>
-            <index name="idx_b24_department_id" columns="b24_department_id"/>
-            <index name="idx_key" columns="key"/>
-            <index name="idx_status" columns="status"/>
+            <index name="b24lib_application_settings_idx_application_installation_id" columns="application_installation_id"/>
+            <index name="b24lib_application_settings_idx_b24_user_id" columns="b24_user_id"/>
+            <index name="b24lib_application_settings_idx_b24_department_id" columns="b24_department_id"/>
+            <index name="b24lib_application_settings_idx_key" columns="key"/>
+            <index name="b24lib_application_settings_idx_status" columns="status"/>
         </indexes>
     </entity>
 </doctrine-mapping>
diff --git a/config/xml/Bitrix24.Lib.Bitrix24Accounts.Entity.Bitrix24Account.dcm.xml b/config/xml/Bitrix24.Lib.Bitrix24Accounts.Entity.Bitrix24Account.dcm.xml
@@ -1,7 +1,7 @@
 <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
                   xmlns:xs="https://www.w3.org/2001/XMLSchema"
                   xmlns:orm="https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
-    <entity name="Bitrix24\Lib\Bitrix24Accounts\Entity\Bitrix24Account" table="bitrix24account">
+    <entity name="Bitrix24\Lib\Bitrix24Accounts\Entity\Bitrix24Account" table="b24lib_bitrix24_accounts">
         <id name="id" type="uuid" column="id">
 
         </id>
@@ -32,4 +32,4 @@
 
         <embedded name="applicationScope" class="Bitrix24\SDK\Core\Credentials\Scope"/>
     </entity>
-</doctrine-mapping>
+</doctrine-mapping>
diff --git a/config/xml/Bitrix24.Lib.ContactPersons.Entity.ContactPerson.dcm.xml b/config/xml/Bitrix24.Lib.ContactPersons.Entity.ContactPerson.dcm.xml
@@ -1,7 +1,7 @@
 <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
                   xmlns:xs="https://www.w3.org/2001/XMLSchema"
                   xmlns:orm="https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
-    <entity name="Bitrix24\Lib\ContactPersons\Entity\ContactPerson" table="contact_person">
+    <entity name="Bitrix24\Lib\ContactPersons\Entity\ContactPerson" table="b24lib_contact_persons">
         <id name="id" type="uuid" column="id">
 
             <generator strategy="NONE"/>
@@ -22,4 +22,4 @@
         <embedded name="fullName" class="Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\FullName"/>
         <embedded name="userAgentInfo" class="Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\UserAgentInfo"/>
     </entity>
-</doctrine-mapping>
+</doctrine-mapping>