Initial SQL-only 1C adapter baseline

2026-07-22 03:03:47 +03:00
commit e2503b77e7
545 changed files with 184711 additions and 0 deletions
@@ -0,0 +1,291 @@
+# 1C Form Discovery And Editing
+
+This runbook adapts the MOXCEL discovery loop to managed forms. The goal is a
+full SQL-side form decoder and safe saved-state editing through the test
+extension, with XML exports used only as evidence fixtures.
+
+## Current Baseline
+
+- Default base: `upo_test`.
+- Default adapter endpoint: `http://docker-gpu.cin.su:8011`.
+- Primary test extension/object fixture:
+  `фс_ДоработкиОбщее` /
+  `DataProcessor.фс_НастройкаУсловногоОформления`.
+- Primary form fixture: `ТестНастройки`.
+- Existing form context evidence:
+  `reports/1c-sql/upo/form-context-test-nastroiki-title-resolution.json`.
+- Existing saved-state smoke selectors:
+  `А`, `ТЗК1`, and `КомандаПример1`.
+
+If `ConfigSave` or `ConfigCASSave` is empty, prepare the working saved-state
+row through the reviewed saved-state copy flow in
+`docs/1c-write-path-safety.md` before running write smokes.
+
+## Current UPO Test Status
+
+- Active form discovery object:
+  `Catalog.ЗадачиАссистентаУправления`.
+- Working saved-state table: `ConfigSave`.
+- Working form payloads:
+  `fa447250-c2a0-439d-8ba7-422923f57200.0` (`ФормаЭлемента`) and
+  `91ce61c5-6f4b-484a-9021-59f18be88550.0` (`ФормаСписка`).
+- The saved-state copy planner now includes form payload rows (`*.0`) with
+  `role=form_payload`; descriptor-only copies are not enough for
+  `metadata.form.decode`.
+- Latest decoder profile after container/dynamic-list baseline mapping:
+  `reports/1c-sql/upo_test/form-profile-zadachi-assistenta-configsave-after-map-live.md`.
+  Coverage is `484/2083` mapped, up from `252/2083`.
+- Latest SQL/XML oracle comparison for `ФормаСписка`:
+  `reports/1c-sql/upo_test/form-sql-xml-compare-zadachi-assistenta-list-xmlmap.md`.
+  It currently shows `17` matched items, `44` matched properties, `41`
+  XML-only properties, and `12` mismatches after mapping SQL type code `8`
+  to `Контекстное меню`.
+- `ТестНастройки` XML context is available at
+  `reports/1c-sql/upo_test/form-context-test-nastroiki-effective-refresh.json`,
+  and the live SQL saved-state rows are prepared in `ConfigCASSave` from local
+  CAS blobs:
+  `f96a0c45-3eff-11f1-8287-005056b0d483__25c39fbf-35a4-4b43-8e3f-cd1f91082c88`
+  plus `.0`.
+- Latest `ТестНастройки` direct SQL decoder profile:
+  `reports/1c-sql/upo_test/form-profile-test-nastroiki-direct.md`.
+  Coverage is `552/2891` mapped after decoding `ExtendedTooltip` form
+  items from marker `12`, table additions from marker `6`, buttons from
+  marker `34`, form/element events, field layout details, group/table layout
+  properties, derived child item references, and section-level command/action
+  semantics.
+- Latest `ТестНастройки` SQL/XML oracle comparison:
+  `reports/1c-sql/upo_test/form-sql-xml-compare-test-nastroiki-direct.md`.
+  It currently shows `68` matched items, `292` matched properties, `2`
+  XML-only properties, no missing SQL items, and no remaining value
+  mismatches after `ExtendedTooltip` decoding, form event decoding from
+  section `1.19`, marker `6`/`34` decoding, element event matching, derived
+  reference semantics, field/group/table layout semantics, plus section-aware
+  XML matching for dynamic-list columns and command-backed buttons. The only
+  remaining XML-only properties are command binding cases:
+  `ТЗИзменитьФорму -> Form.StandardCommand.CustomizeForm` and
+  `ФормаКомандаОбновить -> Form.Command.КомандаПрименить`.
+- Latest `ТестНастройки` write matrix smoke:
+  `reports/1c-sql/upo_test/form-write-matrix-smoke-test-nastroiki-layout-table-100.json`.
+  It verified 100 candidates with zero failures. The current matrix has
+  `2912` entries, `1339` safe smoke candidates, and no not-writable entries.
+  A direct `metadata.write` smoke for `А.Заголовок` also completed as
+  `verified_and_rolled_back`.
+- Latest write matrix smokes:
+  `reports/1c-sql/upo_test/form-write-matrix-smoke-element-50.json` and
+  `reports/1c-sql/upo_test/form-write-matrix-smoke-list-50.json`.
+  Both verified 50 candidates with zero failures.
+- Latest direct `metadata.write` smoke changed `Список.Заголовок` through
+  `apply_and_rollback`; semantic readback verified the change and rollback
+  restored the original SHA1.
+
+## Discovery Loop
+
+Use the same shape as the MOXCEL work:
+
+1. Create or update one controlled form fixture in the test extension.
+2. Change exactly one visible form property in Designer.
+3. Capture the SQL saved-state form payload before and after.
+4. Compare the decoded SQL payload with exported `Ext/Form.xml` as an oracle.
+5. Promote read rules only when SQL bytes reproduce XML-visible facts.
+6. Promote write rules only after `apply_and_rollback` proves semantic readback
+   and rollback.
+
+The adapter runtime remains SQL-only. Exported form XML is a labeling and
+verification fixture, not a runtime input for adapter answers.
+
+## Decoder Scope
+
+The full decoder should expose these public form sections:
+
+- form common properties and events;
+- form items with stable `id`, `name`, parent/group, type, title, data path,
+  visibility, enabled/read-only flags, layout properties, and color/font
+  properties when decoded;
+- form attributes, including value-table fields and dynamic-list fields;
+- form commands, command bars, command-button bindings, and command handlers;
+- table columns, pages, groups, decorations, input fields, labels, buttons,
+  extended tooltips, context menus, and dynamic lists;
+- form module summary and routine/event/command link validation;
+- source-aware display resolution for inherited captions:
+  command title, form attribute title, value-table field title, and local
+  form item override.
+
+Every decoded scalar must carry enough evidence for future writes:
+section, element identity, physical payload path, semantic group/name, current
+value, value type, source, and verification rule.
+
+## Test Extension Fixture Plan
+
+Keep fixtures small and intentionally boring. Add form elements in
+`ТестНастройки` or a sibling test form so each save isolates one concept:
+
+- command button bound to `КомандаПример1`;
+- local-only button title;
+- element title inherited from a form command;
+- element title inherited from a form attribute `А`;
+- element title inherited from a value-table field `ТЗ.К1`;
+- input field with visibility, availability, read-only, title location, choice
+  buttons, quick choice, and text editing flags;
+- group/page/table layout properties: parent group, order, stretch, width,
+  height, command-bar location, and default item;
+- color/font properties for label/button/input field;
+- dynamic list with main table, custom query flag, query text, and columns;
+- form events and element events with matching and missing BSL handlers;
+- structural move/reorder cases inside one parent container.
+
+Prefer one-property saves. Do not combine property, handler, and structural
+changes in the same learning capture.
+
+## Read-Side Commands
+
+Decode a concrete saved-state form payload:
+
+```powershell
+python scripts/smoke_1c_write_matrix.py `
+  --base-url http://docker-gpu.cin.su:8011 `
+  --base-id upo_test `
+  --table ConfigCASSave `
+  --file-name <form-file-name> `
+  --build-only `
+  --report reports/1c-sql/upo_test/form-write-matrix-build.json
+```
+
+Read XML-backed form context for the test fixture:
+
+```powershell
+python scripts/get_1c_form_context.py `
+  --index reports/1c-sql/upo/unified-object-route-index.json `
+  --kind DataProcessor `
+  --name фс_НастройкаУсловногоОформления `
+  --form ТестНастройки `
+  --view effective `
+  --max-items 500 `
+  --output reports/1c-sql/upo_test/form-context-test-nastroiki-effective.json
+```
+
+Adapter RPC equivalents:
+
+```json
+{"method":"metadata.form.decode","payload":{"base_id":"upo_test","table":"ConfigCASSave","file_name":"<form-file-name>","include_parameters":true,"max_items":5000,"max_parameters":500}}
+```
+
+```json
+{"method":"metadata.form.write_matrix.build","payload":{"base_id":"upo_test","table":"ConfigCASSave","file_name":"<form-file-name>"}}
+```
+
+Build a decoder coverage and gap profile for an object form:
+
+```powershell
+python scripts/profile_1c_forms.py `
+  --adapter-url http://docker-gpu.cin.su:8011 `
+  --base-id upo_test `
+  --kind Catalog `
+  --name ЗадачиАссистентаУправления `
+  --table Config `
+  --raw-output-json reports/1c-sql/upo_test/form-profile-zadachi-assistenta-details.json `
+  --output-json reports/1c-sql/upo_test/form-profile-zadachi-assistenta.json `
+  --output-markdown reports/1c-sql/upo_test/form-profile-zadachi-assistenta.md
+```
+
+Compare decoded SQL form semantics with exported `Form.xml` semantics:
+
+```powershell
+python scripts/compare_1c_form_sql_xml.py `
+  --sql-details reports/1c-sql/upo_test/form-profile-zadachi-assistenta-configsave-xmlmap-details.json `
+  --xml-context reports/1c-sql/upo_test/form-context-zadachi-assistenta-list-effective.json `
+  --output-json reports/1c-sql/upo_test/form-sql-xml-compare-zadachi-assistenta-list-xmlmap.json `
+  --output-markdown reports/1c-sql/upo_test/form-sql-xml-compare-zadachi-assistenta-list-xmlmap.md
+```
+
+## Write Learning
+
+For a manual one-property Designer change:
+
+```json
+{"method":"metadata.write_learning.capture_before","payload":{"base_id":"upo_test","learning_id":"form-visible-case","table":"ConfigCASSave","form":"ТестНастройки","element":"<element-name>"}}
+```
+
+After the Designer save:
+
+```json
+{"method":"metadata.write_learning.capture_after","payload":{"base_id":"upo_test","learning_id":"form-visible-case","table":"ConfigCASSave","form":"ТестНастройки","element":"<element-name>"}}
+{"method":"metadata.write_learning.diff","payload":{"learning_id":"form-visible-case"}}
+{"method":"metadata.write_learning.infer_rule","payload":{"learning_id":"form-visible-case"}}
+```
+
+Promote a rule only when the diff changes exactly one intended semantic value
+or one intended structural relation. Composite/list rewrites need a dedicated
+source-specific rule, not a generic scalar writer.
+
+## Write Verification
+
+Run the existing source-aware route smoke:
+
+```powershell
+python scripts/smoke_1c_saved_state_write_routes.py `
+  --base-url http://docker-gpu.cin.su:8011 `
+  --base-id upo_test `
+  --table ConfigCASSave `
+  --file-name <form-file-name> `
+  --report reports/1c-sql/upo_test/saved-state-write-routes-smoke.json
+```
+
+Then run the matrix smoke:
+
+```powershell
+python scripts/smoke_1c_write_matrix.py `
+  --base-url http://docker-gpu.cin.su:8011 `
+  --base-id upo_test `
+  --table ConfigCASSave `
+  --file-name <form-file-name> `
+  --max-candidates 50 `
+  --learning-id upo-test-form-write-matrix `
+  --report reports/1c-sql/upo_test/form-write-matrix-smoke-50.json
+```
+
+Successful writes must use `apply_and_rollback`, explicit SQL apply and
+rollback gates, sha1 preconditions, backup evidence, semantic readback through
+`metadata.form.decode`, and rollback verification.
+
+## Promotion Gates
+
+Read rule promotion requires:
+
+- SQL-only decoder output with stable semantic name and value type;
+- XML fixture agreement for the same form element/property;
+- no dependency on display strings when a stable id/path exists;
+- regression coverage on the test form and at least one real extension form.
+
+Write rule promotion requires:
+
+- exact physical payload path or structural span evidence;
+- source-aware routing for inherited display values;
+- `metadata.form.write_target.resolve` success with a deterministic target;
+- `metadata.form.element.write_apply` or `metadata.write` success in
+  `apply_and_rollback`;
+- semantic verification and rollback readback success;
+- registration in the scalar/enum/verified write matrix reports.
+
+## Immediate Work Queue
+
+1. Refresh the test form saved-state row for `upo_test` if
+   `ConfigCASSave`/`ConfigSave` is empty.
+2. Capture a fresh `metadata.form.decode` baseline for `ТестНастройки`.
+3. Build a form property gap report: decoded SQL semantics versus `Ext/Form.xml`
+   semantics from the test extension.
+4. Learn the two remaining command binding cases with a one-property
+   before/after capture: standard command button binding and local button to
+   form command binding. Do not hard-code these from display names. Current
+   captures and exact after-capture commands are in
+   `docs/runbooks/1c-form-command-binding-learning.md`.
+5. Expand `parser/form_payload.py` for the next write-relevant properties:
+   availability, read-only, title location, command-bar location, colors, font,
+   and dynamic-list query settings.
+5. Rebuild the write matrix and split entries into verified scalar, enum,
+   composite-needs-rule, identity/binding, and structural queues.
+6. Learn one property at a time through
+   `metadata.write_learning.capture_before/capture_after/diff/infer_rule`.
+7. Promote safe scalar/enum routes into smoke coverage.
+8. Add a structural movement scorecard for sibling reorder and parent/group
+   movement, then extend `metadata.form.target.move` beyond sibling swaps only
+   after controlled round-trip proof.