Story: Book data model cleanup
Table of Contents
This page documents a story in Sprint 23. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Carried from Sprint 22, where 3 of 9 tasks were completed.
Goal
Fix the data-modeling errors found by reviewing book.org against the Book domain knowledge cluster, and address the remaining domain-fit gaps it surfaced (classification flags, hierarchy semantics, legal entity/branch, rates centre, currency naming, allowed lists, manual enrichment).
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 23 |
| Now | 13/13 tasks done. All data-modeling bugs fixed, classification lookup entities shipped, hierarchy/legal-entity/allowed-lists/Wash-link questions resolved (implementation or sizing, as appropriate), rates centre and functional_currency rename shipped, manual chapter enriched, and Book window toolbar buttons added via the existing codegen facet. |
| Waiting on | Nothing. |
| Next | Nothing – story complete. |
| Last touched | 2026-07-15 |
Acceptance
- Every data-modeling bug surfaced by the original book.org review (book_status, is_trading_book/regulatory_book_type) is fixed.
- book_purpose_type, ledger_feed_type, is_sweepable, and rates_centre_code are shipped as proper lookup-entity/soft-FK fields, each manually QA'd.
- Domain-fit questions raised by the review (book-to-book hierarchy, legal entity/branch, allowed-currency/product lists, Wash paired-risk-book link) are each resolved: either implemented, or explicitly sized/analysed with a written recommendation and a follow-up capture where implementation was out of scope.
ledger_ccyrenamed tofunctional_currencyend to end (domain model, SQL, C++, Qt, and living documentation).- Books manual chapter enriched with domain concepts, not just UI mechanics.
- Book window exposes its lookup children via toolbar buttons, mirroring Currency's existing pattern.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Fix book_status to reference the book_statuses lookup table | DONE | 2026-07-08 | 2026-07-09 | book_status is currently a static_combo with a hand-typed 5-value list (Active/Inactive/Closed/Frozen/Pending) that does not match the real ores_refdata_book_statuses_tbl (seeded with only Active/Closed/Frozen). Once out of bootstrap mode, saving Inactive or Pending is rejected by ores_refdata_validate_book_status_fn. Fix by referencing the lookup table properly (FK-style combo, like currency's rounding_type/market_tier), and keep badge colours in sync with the real values. |
| Fix is_trading_book domain type from int to bool | DONE | 2026-07-08 | 2026-07-09 | is_trading_book is modeled as type: integer / cpp_type: int even though it is semantically boolean; type: boolean/cpp_type: bool is natively supported elsewhere (e.g. zero_convention, market_series). Fix across domain/SQL/repository/protocol layers. Escalated into a proper regulatory_book_type lookup entity (Basel III/IV FRTB classification). |
| Add book_purpose_type lookup entity to book | DONE | 2026-07-11 | 2026-07-13 | Rescoped from the original 5-boolean-flags ask after analysis: add book_purpose_type as a lookup entity, mirroring the regulatory_book_type pattern, with mutually-exclusive values Trading (default/ordinary), Reserve, Funding, Wash, Write-off, Test, Sales, Sweep target, and Remittance target. Companion fields (ledger_feed_type, is_sweepable, Wash's paired-risk-book link) are split into their own tasks below. Manual QA surfaced and fixed two pre-existing gaps in the entity-creation workflow (NATS handler registrar, tenant-provisioning copy block) unrelated to this entity's own code. |
| Document that book-to-book hierarchy is not supported; hierarchy is via portfolios | DONE | 2026-07-13 | 2026-07-13 | The domain notes describe an accounting-side book hierarchy (a book containing child books via ledger setup, a single Root Book). ORE Studio does not model this: Book has no self-referencing parent field. This is a deliberate design decision, not a gap – hierarchy is expressed entirely via the portfolio tree (Portfolio has self-referencing parent_portfolio_id; Book links to exactly one portfolio). Update the Book domain knowledge docs (books_and_portfolios.org) and the manual chapter to state this explicitly as a design choice, not an open gap. |
| Investigate legal entity and branch fields for book | DONE | 2026-07-13 | 2026-07-13 | The domain notes state a book belongs to exactly one legal entity, business, and branch. Book currently has party_id and an optional owner_unit_id (business unit) but no legal entity or branch field, and no Legal Entity or Branch entity exists in the codebase at all. Investigate whether party/business_unit already cover this semantically, or whether new fields/entities are needed, and produce a recommendation. |
| Add rates centre to book, reusing business_centre | DONE | 2026-07-13 | 2026-07-13 | Each book should be assigned a rates centre so books sharing a centre revalue against consistent market data (see book_groups_and_rates_centres.org). Check whether the existing business_centre entity (Commission: business_centre story) is the right fit to reuse for this, rather than modeling a new rates-centre entity, and add the FK to book. |
| Rename ledger_ccy to functional_currency | DONE | 2026-07-14 | 2026-07-14 | ledger_ccy is described in the domain notes as the book's functional/accounting currency, designated by the ledger. Rename the field (and its Qt label, column header, etc.) to functional_currency to match domain terminology precisely. |
| Analyse allowed-currency and allowed-product lists for book (needs further design) | DONE | 2026-07-13 | 2026-07-13 | Book Currencies (domain notes): each book has a set of allowed currencies; only instruments whose currency intersects that set may be booked into it. Likely also needs an allowed-product-type list (books carry trading rules restricting which deals may be booked). Both probably need an explicit 'All' wildcard state distinct from an enumerated set. Needs further design analysis before implementation – data shape (multi-value column vs junction table), UI (multi-select vs checkbox-per-value), and how 'All' interacts with an otherwise-enumerated list. |
| Enrich the Books manual chapter with domain concepts | DONE | 2026-07-10 | 2026-07-10 | chapter_7_books.org currently documents only the Qt UI mechanics. Weave in the domain concepts from the new Book knowledge cluster (classification, books vs portfolios, lifecycle, ledger connection) so the manual explains what a book represents and why, not just how to click through its dialogs. |
| Add ledger_feed_type lookup entity to book | DONE | 2026-07-13 | 2026-07-13 | Replace the originally-scoped is_ledger_book/is_manual_ledger_book boolean pair with one 3-state ledger_feed_type field (None/Automatic/Manual), following the regulatory_book_type lookup-entity pattern – removes the invalid state where manual=true but ledger=false. |
| Add is_sweepable flag to book | DONE | 2026-07-13 | 2026-07-13 | Add the is_sweepable boolean (spot-sweep eligibility only, unrelated to ledger sweep), rendered as a yes/no badge in the Book list consistent with the regulatory_book_type badge combo. |
| Add paired risk-book link for Wash-purpose books | DONE | 2026-07-13 | 2026-07-13 | A Wash-purpose book needs a nullable self-referencing FK to its designated risk book, since every wash back-to-back trade needs a routing target. Design validation (only settable when book_purpose_type = Wash) and scope size before pulling into a sprint – discovered during the book_purpose_type design, not in original ask. |
| Add child-entity toolbar buttons to Book window | DONE | 2026-07-14 | 2026-07-15 | Book's MDI window should expose its lookup children (book_status, regulatory_book_type, book_purpose_type, ledger_feed_type) as toolbar buttons that open their respective list windows, mirroring CurrencyMdiWindow's RoundingType/MarketTier toolbar pattern. |