Story: Codegen support for view groups (Qt detail-dialog tabs)

Table of Contents

This page documents a story in Sprint 22. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Restore the ability to group an entity's detail-dialog fields into separate tabs — lost when currency was migrated onto the shared Qt codegen templates — as a generic, reusable codegen concept (view_group) rather than a currency-specific patch, piloted on currency (the entity that had it and lost it), and document the result in the manual.

Status

Field Value
State DONE
Parent sprint Sprint 22
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-07-10

Acceptance

  • [X] The entity_org schema (codegen_input_org_schema.org) gains an optional per-field view_group column in the Detail fields table (*** Detail fields under ** Qt). Fields with no view_group default to a single implicit tab (backward compatible with every existing entity — verified mechanically via zero-diff regeneration, not just asserted).
  • [X] The Qt detail-dialog codegen templates (qt_detail_dialog_ui.mustache, via compute_view_groups() in core.py) generate one QWidget tab per distinct view_group (in first-appearance order), each with its own QFormLayout, instead of always emitting a single generalTab. The generic Provenance tab is unaffected. cpp_qt_detail_dialog.{hpp,cpp}.mustache needed no changes (confirmed, not assumed).
  • [X] Currency's entity_org model updated with view_group values matching the pre-codegen tabs exactly (recovered from git history): General, Formatting, Rounding — Provenance unaffected.
  • [X] Currency regenerated and manually verified live: 6/6 test steps PASSED (all four tabs, correct fields, editing/saving, tab-switch state preservation).
  • [X] Manual chapter 5 screenshots retaken against the regenerated dialog and cropped to just the dialog window — 5/5 test steps PASSED. currency_details_rounding.png embedded in the chapter for the first time (pre-existing gap, fixed alongside the others).
  • [X] No additional currency domain knowledge gaps surfaced — prose re-verified field-by-field against the live dialog and found accurate as written.

Tasks

Task State Start End Description
Scaffold story: Codegen support for view groups (Qt detail-dialog tabs) DONE 2026-07-09 2026-07-09 Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR.
Design and add view_group support to the entity_org schema and Qt codegen templates DONE 2026-07-09 2026-07-10 Add an optional view_group column to the Detail fields table and generate one dialog tab per distinct view_group.
Apply view_group tabs to the currency entity (pilot) DONE 2026-07-10 2026-07-10 Model currency's fields into the pre-codegen tab grouping, regenerate, verify.
Document currency domain knowledge in the manual DONE 2026-07-10 2026-07-10 Retake chapter 5 screenshots against the restored tabs; fix the missing Rounding screenshot; add any newly-surfaced domain knowledge.

Decisions

  • view_group grouping is computed in core.py, after the existing per-field enrichment loop, not in org_loader.py as originally planned — some entities never declare an explicit Detail fields table (core.py auto-generates a minimal one from columns when absent), and that fallback path runs after org_loader.py. Grouping earlier would have silently skipped every auto-generated-detail_fields entity. Factored into a standalone, directly unit-testable compute_view_groups() function rather than left inlined.
  • Byte-identical backward compatibility for the no-view_group case required hard-coding the exact legacy widget names/title (including the group box's "Basic Information" title, distinct from the tab's own "General" title) rather than deriving them generically — a naive "tab title = group box title = group name" scheme would have silently changed every existing entity's generated .ui.
  • While verifying the currency pilot live, discovered and fixed a real, systemic bug unrelated to view_group itself: every generated Client*Model::fetch_*() checked transport-level failure but never the response's own success=/=message fields, silently turning a genuine backend failure (e.g. a stale-schema SQL error) into "0 rows loaded" with no visible error. Fixed at the shared codegen template source, regenerated for currency only (other entities' protocol structs predate the success=/=message fields the current protocol template already generates unconditionally — broader rollout needs each entity's protocol confirmed current first, tracked separately).

Out of scope

  • Any UI grouping mechanism beyond Qt detail-dialog tabs (e.g. table column grouping, report sections) — view_group is named generically in case other projections want it later, but this story only implements the detail-dialog-tab consumer.
  • Restoring exact pixel-level layout/spacing from the pre-codegen dialog — only the field-to-tab grouping, using the same generated widget conventions every other codegen'd entity already uses.

Emacs 29.3 (Org mode 9.6.15)