odant-work 1.0.12 → 1.0.14

package/sources/data/readme.md

@@ -0,0 +1,77 @@
+# sources/data — учётное ядро на SQLite (архитектура ODANT → WORK)
+
+## 1. Что это
+
+Модуль хранения и обработки прикладных учётных данных WORK: дерево учётных классов, объекты справочников (`$catalog`), составные структуры (`$struct`), виртуальные справочники (`$virtual`), первичные операции (`$operation`) и явная двойная запись в классы счетов (`$account`) единого журнала (`$register`).
+
+Каждая организация (`$base` в `/ORGANIZATIONS/<Организация>`) хранит свои учётные данные в собственной изолированной БД `node:sqlite` (`<Организация>/$base/#system/work.db`). Полная архитектурная спецификация зафиксирована в [`docs/architecture-v2.md`](/docs/architecture-v2.md/~/handlers/pages/form/).
+
+## 2. Зачем это нужно
+
+Метаданные классов, экранные формы и печатные шаблоны остаются файлами дерева WORK (наследуются по трём осям: `Types` → `Ancestor` в `/MODULES` → `Parent` → `Сам класс`), а учётные объекты и движения по счетам получают транзакционность, индексацию, явную двойную запись по классам счетов и двухэтапную аналитическую отчётность со скоростью Си-движка `node:sqlite`.
+
+## 3. Как это работает
+
+- **Изолированная БД организации (`db.js`):**
+  - Для каждой `$base` открывается собственная БД `<Организация>/$base/#system/work.db` (`dataDb(basePath)`). Данные разных организаций никогда не смешиваются.
+  - Схема ведётся миграциями по `PRAGMA user_version`. `tx()` выполняет синхронную функцию в транзакции (вложенный вызов — `SAVEPOINT`).
+- **Классы и домены (`classes.js`):**
+  - Идентификатор любого класса (`cid`) — его реальный путь в дереве WORK (`path`). Никаких искусственных `CID` не используется.
+  - Сканирование охватывает домены `/MODULES` (`$module`), `/ORGANIZATIONS` (`$base`, `$structure`) и подключённые внутри организаций модули (`/ORGANIZATIONS/<Орг>/MODULES/<Модуль>`).
+  - Иерархия хранится в таблице замыкания `class_tree`: потомки и предки любого класса выбираются одним SQL-запросом.
+  - Модули (`$module`) поддерживают блокировку (`disabled` / `set_enabled`) как на уровне отдельной организации (`$base/MODULES/<Модуль>`), так и на уровне всей системы (`/MODULES/<Модуль>`).
+- **Трёхосевое наследование и схема (`schema.js`):**
+  - Метаданные класса (`FIELDS`, `STATIC`, `POSTINGS`, `OVERLAY`, `SOURCE`, `NORMS`) собираются по трём осям в порядке приоритета:
+    `1. Types (миксины) → 2. Ancestor (одноимённый класс в /MODULES) → 3. Parent (родитель в дереве) → 4. Сам класс`.
+  - Ссылки на справочники и счета (`target`, `catalog`, `account`) автоматически привязываются к контексту текущей организации (`resolveInBase`).
+  - Типы полей: `string`, `text`, `number`, `money`, `integer`, `boolean`, `date`, `datetime`, `link` (`$catalog` / `$virtual`), `struct` (`$struct` при `table: false`), `table` (`$struct` или инлайн-поля при `table: true`), `enum`, `file`.
+- **Классы данных (`$catalog`, `$virtual`, `$struct`):**
+  - **`$catalog`** — единый тип реального справочника: группа агрегирует объекты всех дочерних классов, лист хранит объекты.
+  - **`$virtual`** — виртуальный справочник поверх базового справочника и счёта (`SOURCE: { registry, account, slot, mode }`):
+    - `mode: 'turnover'` — все объекты, участвовавшие в оборотах счёта («Клиенты», «Поставщики»);
+    - `mode: 'balance'` — объекты с ненулевым остатком на дату («Сотрудники», «В отпуске»).
+    - Поддерживаются вложенные специализированные `$virtual` (например, `CATALOGS/Сотрудники/В отпуске`), наследующие `SOURCE` и `OVERLAY` родителя и дополняющие их собственными полями расширения (`ext_of`).
+  - **`$struct`** — составная структура полей («Адрес», «Паспорт», «Единица измерения»). Поддерживается произвольная глубина рекурсивной вложенности структур (`Паспорт → Адрес`) и признак табличной части `table: true`.
+- **Объекты и версии во времени (`objects.js`):**
+  - Объекты создаются только в классах-листьях (`$catalog`, `$operation`).
+  - Тело проверяется по схеме (`DataError.errors` передаётся в UI через `X-Work-Errors` с подсветкой конкретных полей и ячеек таблиц).
+  - Каждая запись сохраняет версию с `valid_from`; `readObject(id, { at })` возвращает состояние реквизитов на дату операции.
+  - Выборки `queryObjects` поддерживают фильтрацию `where` по точечным путям вложенных структур (`passport.address.city`), полнотекстовый поиск, фильтр подразделений (`unit`), сортировку и пагинацию.
+- **Явная двойная запись и проведение операций (`posting.js`, `expr.js`):**
+  - При проведении операции (`$operation`) каждое правило `POSTINGS` создаёт в `account_entries` **две отдельные записи**:
+    1. запись в классе счёта Дебета (`$account`) со значениями только тех аналитик, которые объявлены на счёте Дебета;
+    2. запись в классе счёта Кредита (`$account`) со значениями только тех аналитик, которые объявлены на счёте Кредита.
+  - Обе записи связаны общим номером проводки `entry_id` и ссылкой на операцию `op_id`.
+  - Проведённая операция неизменяема: исправление (`correctOperation`) и отмена (`cancelOperation`) выполняются только через честное **сторно** прежних записей и создание новых.
+  - При проведении, исправлении или отмене операции задним числом автоматически выполняется каскадный пересчёт зависимых списаний по скользящей средней `unit_cost(...)` (`repostDependentOperations`).
+  - Каждая регистрация/исправление/отмена операции записывает факт в `data.logs` подразделения и автора (`logOperationFact`).
+- **Двухэтапные аналитики и отчёты (`reports.js`):**
+  - Поля справочника-аналитики и поля его расширения `OVERLAY` выступают как **субаналитики** (`resolveAnalyticsFilter`): сначала отбираются или группируются объекты справочника по их полям, затем по найденным `id` фильтруются и агрегируются движения счёта.
+  - `trialBalance` (`db_sheet`) — Экран 1 (Общая ОСВ по дереву счетов) и Экран 2 (Анализ счёта в разрезе аналитик и субаналитик `by`).
+  - `accountTurnovers` (`db_turnovers`) — Экран 3 (двухпанельные Обороты счёта с группировкой `groupBy`: `none | day | week | month | quarter | year | operation | account | all` и списком первичных документов периода).
+  - `readEntry` (`db_entry`) — Экран 4 (сборная карточка проводки из записи счёта Дебета и записи счёта Кредита).
+  - `accountCard` (`db_card`) — карточка проводок счёта с текущим сальдо после каждой записи.
+  - `journal` (`db_journal`) — журнал проводок с фильтром `effective`.
+- **Экранные формы в проводнике ODA (`work-form`):**
+  - Единственный UI — штатные вкладки проводника ODA с единой полосой периодов `oda-packets` сверху:
+    - `$register` → `form/sheet` (Экран 1: Общая ОСВ) и `form/journal` (Журнал проводок);
+    - `$account` → `form/postings` (режимы `card`, `analysis` — Экран 2, `turnovers` — Экран 3, модальная `entryCard` — Экран 4);
+    - `$catalog`, `$operation` → `form/objects` (единая форма списка и редактирования объектов, предпросмотр проводок, кнопки печати);
+    - `$virtual` → `form/virtual` (состав виртуального справочника на дату и редактирование полей `OVERLAY`).
+- **Инструменты ИИ-агента (`sources/modules/agent/tools/work/data.js`):**
+  - `describe_class` (`db_schema`), `find_objects` (`db_query` / `db_members`), `register_operation` (`db_preview` / `db_create` / `db_register` / `db_correct` / `db_cancel` с подтверждением человека на запись), `report` (`sheet | turnovers | card | journal | entry`).
+
+## 4. Из чего это состоит
+
+- `db.js` — открытие изолированной БД организации (`<Организация>/$base/#system/work.db`), миграции, `tx`, настройки (`closed_until`)
+- `classes.js` — синхронизация дерева классов (`MODULES`, `ORGANIZATIONS`), таблица замыкания `class_tree`, проверка блокировки модулей
+- `expr.js` — безопасный вычислитель формул сумм, количеств и условий в `POSTINGS` и печатных шаблонах
+- `schema.js` — трёхосевая сборка схемы класса (`Types` → `Ancestor` → `Parent` → `Сам класс`), разрешение ссылок `resolveInBase`, валидация правил листа
+- `objects.js` — создание, версионирование (`valid_from`), чтение на дату, валидация вложенных структур `$struct` и табличных частей `table: true`, выборки `queryObjects`
+- `posting.js` — явная двойная запись в `account_entries`, сторно, `norm()`, `coef()`, `unit_cost()`, каскадный пересчёт `repostDependentOperations`, запись в `data.logs`
+- `reports.js` — `trialBalance`, `accountTurnovers`, `accountCard`, `readEntry`, `journal`, `objectState`, `objectTrajectory`, `virtualMembers`, двухэтапные субаналитики
+- `choices.js` — `linkChoices` для полей-ссылок (`oda-link-input`) с учётом состава виртуального справочника на дату
+- `scope.js` — права и область видимости (`own`, `place`, `unit`, `all`) по ссылкам рабочих мест (`LINKS` в `ROLES`)
+- `print.js` — наследование и рендеринг HTML-шаблонов печати (`<класс>/$operation/print/*.html`), сумма прописью
+- `api.js` — серверные методы `db_*` на прототипе `$class`, `classObjectCount` для счётчиков в дереве проводника
+- `time.js`, `errors.js` — работа с локальными датами/периодами и структурированные ошибки `DataError`