Task: Add portfolio entity chapter to the user manual
Table of Contents
This page documents a task in the Commission: portfolio story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Add the portfolio entity chapter to the user manual, following the pattern of the book and counterparty chapters — documenting portfolio's Qt windows (list, detail, history) and behaviours once the codegen/drift task has landed a commissioned baseline.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Commission: portfolio |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-07-18 |
Acceptance
[X]Portfolio entity chapter added to the manual, documenting the Qt list, detail, and history windows and their behaviours.[X]Manual builds cleanly (PDF/site) with the new chapter included.
Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
Notes
- 2026-07-17: While working the screenshot-capture scenario (Capture
screenshots for the Portfolios manual chapter), the Portfolios
list and detail screens showed wrong badge colours (Status,
IsVirtual). Traced to Improve badge colour scheme support
(sprint 23, owned by
bright_faraday) being started but not finished — its highest-leverage task (thebadge_mappingbrowser UI) is itself BLOCKED, and the coverage-audit/self-badging tasks are still BACKLOG. Screenshotting the Portfolios chapter now would capture the wrong colours into shipped manual images. Blocked this task on that story rather than working around it with a one-off fix scoped to portfolio; see the badge story for the actual remediation work.
Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario, run
through the QA Validation Runner panel) that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
| Capture screenshots for the Portfolios manual chapter | PASSED | 7/7 steps passed. |
PRs
| PR | Title |
|---|---|
| #1636 | [refdata,doc] Add portfolio manual chapter, fix history provider |
Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 (PR #1636, round 1) | Scenario Notes field has raw scratch text instead of a proper ... link | scenario_portfolios-manual-screenshots.org | Accepted | Replaced with a link to the wired-in image plus context on the deleted raw capture and the follow-up task it informed. |
| 2 (PR #1636, round 1) | portfolio_* includes out of alphabetical order relative to party_status_*/party_type_* | registrar.cpp | Accepted | Reordered. |
| 3 (PR #1636, round 2) | Round 1's reorder was incomplete: portfolio_* still sat before payment_frequency_* | registrar.cpp | Accepted | Fixed properly this time (party_type -> payment_frequency -> portfolio -> purpose_type), verified with a sort diff over both include blocks, not just the immediate neighbours. |
Result
Resumed once the badge colour scheme story's mapping-browser task
landed (PR #1622) and Portfolios badge colours were confirmed
correct. Captured all four screenshots via the QA Validation Runner
and manual desktop captures, cropped with PIL, and wired into
chapter_portfolios.org, replacing the [SCREENSHOT NEEDED]
placeholders: portfolios_main_dialog, portfolio_details_general,
portfolio_status_combo, portfolio_history_dialog.
Found and fixed one real bug along the way: opening a portfolio's
History dialog failed with "No history provider registered for
entity_type: ores.refdata.portfolio" – every supporting piece
(portfolio_service::get_portfolio_history,
render_portfolio_fields) already existed, just the
registrar.cpp registration was never added. Also found (separately,
not fixed here) that the Qt-embedded manual differed from the PDF
because deploy_help_qch alone doesn't take effect until
ores.qt.exe is rebuilt (the .qch is a compiled-in Qt resource),
and that user_manual_site.org's Chapters table was missing two
pre-existing chapters (chapter_parties=/=chapter_counterparties)
entirely – fixed both, and hardened
How do I document an entity?'s validation
step with an automated cross-check instead of manual eyeballing.
Filed two follow-up tasks, neither blocking this chapter: Model portfolio_status as a proper lookup entity (currently a hardcoded static_combo, unlike book_status) and Purpose Type combo shows raw codes, not display labels.
Verified: manual QA scenario 7/7 steps PASSED, including the Qt client's Help viewer and the rebuilt PDF.