Task: Appraise book_status across all layers and produce evaluation checklist
This page documents a task in the Commission: book_status story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
Score book_status across all layers using the domain entity evaluation checklist. Record findings per layer to identify codegen drift, missing SQL criteria, and absent UI surface.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Commission: book_status |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-26 |
3. Acceptance
- Evaluation checklist filled in for every criterion. Every gap has a 'Fix' or 'Accept' decision recorded. Findings are summarised in the Result section to guide remaining tasks.
4. Plan
Read all book_status source files layer by layer and score them against the Domain entity evaluation checklist. Meta-type: Auxiliary type (lookup table of lifecycle states for book records; referenced as a soft-FK from book). book_status has its own MDI window so Qt criteria apply as "If applicable → Yes".
5. Notes
5.1. DB layer
| Item | Result | Notes |
|---|---|---|
| Table exists | ✅ | refdata_book_statuses_create.sql |
tenant_id column |
✅ | |
version column |
✅ | |
modified_by |
✅ | |
performed_by |
✅ | set by trigger from ores_iam_current_service_fn() |
change_reason_code |
✅ | |
change_commentary |
✅ | |
valid_from / valid_to |
✅ | |
| CHECK: temporal order | ✅ | |
| CHECK: code not empty | ✅ | |
| GIST exclusion constraint | ✅ | |
| Primary key | ✅ | (tenant_id, code, valid_from, valid_to) |
| Version unique index | ✅ | |
| Natural key unique index | ✅ | |
| Tenant index | ✅ | |
display_order column |
✅ | Aux: Always |
description column |
✅ | Aux: Always |
| Insert trigger | ✅ | version management, optimistic locking |
Insert trigger: security definer + set search_path |
✅ | Accept — fixed in SQL verify task |
| Soft-delete rule | ✅ | |
| Validation function | ✅ | ores_refdata_validate_book_status_fn |
Validation function: security definer + set search_path |
✅ | |
Validation function: bootstrap valid_to filter |
✅ |
5.2. Domain layer (C++)
| Item | Result | Notes |
|---|---|---|
| Domain struct | ✅ | ores.refdata/api/include/ores.refdata.api/domain/book_status.hpp |
| All business columns represented | ✅ | code, name, description, display_order, modified_by, performed_by, change_reason_code, change_commentary, recorded_at, version |
display_order field |
✅ | |
description field |
✅ | |
recorded_at |
✅ | std::chrono::system_clock::time_point |
| Canonical C++ types | ✅ | |
| No logic in struct | ✅ |
5.3. Repository layer (C++)
| Item | Result | Notes |
|---|---|---|
| Entity class | ✅ | |
| Mapper class | ✅ | |
| Repository class | ✅ | |
| write (save single + batch) | ✅ | |
| read_latest (list) | ✅ | |
| read_latest by code (get) | ✅ | |
| read_all by code (history) | ✅ | |
| remove (single + batch) | ✅ | |
| count method | ❌ | No get_total_<entity>_count in repository; checklist requires it; Fix — add to repo, service, protocol |
5.4. Service layer (C++)
| Item | Result | Notes |
|---|---|---|
| Service class | ✅ | |
| list_statuses | ✅ | |
| get_status | ✅ | |
| save_status / save_statuses | ✅ | |
| remove_status / remove_statuses | ✅ | |
| get_status_history | ✅ | |
| count_statuses | ❌ | Missing; Fix — align with count gap in repository |
| Authorization checks | ✅ | Accept — in handler (has_permission calls in book_status_handler.hpp); service delegates to context; acceptable pattern |
| NATS event firing on mutation | ❌ | No nats_ calls in book_status_service.cpp; save/delete should publish a changed event so connected clients update their dropdowns; Fix — add event publish on save and delete |
5.5. Messaging / JSON IO layer (C++)
| Item | Result | Notes |
|---|---|---|
| JSON IO header | ✅ | book_status_json_io.hpp — streaming operator |
| Protocol header | ✅ | book_status_protocol.hpp |
| Mutation message types | ✅ | save_book_status_request/response, delete_book_status_request/response |
| Query message types (list, history) | ✅ | get_book_statuses_request/response, get_book_status_history_request/response |
count_book_statuses_request |
❌ | Missing; Fix — add with count gap above; nats-handler will also need a route for this message type |
get_book_status_request (single) |
✅ | Accept — single-fetch served by filtered list protocol (get_book_statuses_request with code filter); no standalone message type needed |
5.6. nats-eventing profile
| Item | Result | Notes |
|---|---|---|
book_status_changed_event.hpp |
❌ | Not generated; eventing/ dir has currency, country, monetary_nature, book but not book_status; Fix — run nats-eventing codegen profile (separate task). Prerequisite for service event publish fix (item 3 in Result); also prerequisite for live-dropdown fix via nats-handler subscription. |
5.7. nats-handler profile
| Item | Result | Notes |
|---|---|---|
book_status_handler.hpp |
✅ | ores.refdata.core/include/.../messaging/book_status_handler.hpp. Handler does not subscribe to book_status_changed_event (event type not yet generated; unblocked for now but blocks live-dropdown fix once eventing is wired). Handler internals deferred to messaging codegen sync task. |
5.8. Qt layer
| Item | Result | Notes |
|---|---|---|
| MDI list window | ✅ | BookStatusMdiWindow.hpp/cpp |
| Detail dialog | ✅ | BookStatusDetailDialog.hpp/cpp |
| History dialog | ✅ | BookStatusHistoryDialog.hpp/cpp |
| Controller | ✅ | BookStatusController.hpp/cpp |
| Client model | ✅ | ClientBookStatusModel.hpp/cpp |
| .ui files | ✅ | BookStatusDetailDialog.ui, BookStatusHistoryDialog.ui |
| Dropdown in parent dialog | ❌ Partial | BookDetailDialog::populateBookStatusCombo() exists but is hardcoded ("Active", "Closed", "Frozen") with a TODO to fetch from NATS service; Fix — implement async fetch from get_book_statuses_request |
| Live UI verification | ⬜ | Deferred — separate verification task (⬜ = scoped to a separate task, not a codegen gap) |
5.9. Shell layer
| Item | Result | Notes |
|---|---|---|
| Submenu registered | ❌ | No shell commands for book_status; Fix — separate task |
| list / add / remove / history commands | ❌ | Not implemented |
5.10. CLI layer
| Item | Result | Notes |
|---|---|---|
| list / add / remove subcommands | ❌ | Not implemented; Fix — same task as shell |
5.11. HTTP / Wt layers
Deferred — captured as backlog task (file_wt_http_captures).
5.12. Manual
| Item | Result | Notes |
|---|---|---|
| Entity chapter | ❌ | Not yet written; Fix — separate documentation task |
6. PRs
| PR | Title |
|---|---|
| #1334 | [agile] Appraise book_status across all layers |
7. Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 | Implicit Accept on ✅ rows; SQL verify task link missing | task_appraise | Fix | Made Accept explicit; linked SQL verify task |
| 2 | nats-handler/eventing asymmetry not explained | task_appraise | Fix | Added prerequisite notes to eventing and handler rows |
| 3 | Qt "12 artefacts" count source unclear | task_sync_qt | Accept | Count correct and verifiable |
| 4 | get_book_status_request bundled with count Fix | task_appraise | Fix | Separated into two rows: count ❌ Fix, single-fetch ✅ Accept |
| 5 | Fix #4 groups nats-handler+Qt codegen | task_appraise | Fix | Split into items 4 (messaging) and 5 (Qt); renumbered |
| 6 | nats-handler scope note absent | task_appraise | Fix | Added "deferred to messaging codegen sync task" note |
| 7 | PR description claims "add 5 tasks" but they pre-exist | PR body | Accept | Body already submitted; noted for record |
| 8 | story.org #+updated not bumped | story | Fix | Bumped to 2026-06-26 |
| 9 | Count gap scope: nats-handler route also needed | task_appraise | Fix | Result item 1 now includes nats-handler route |
| 10 | NATS event publish dependency not explicit | task_appraise | Fix | Items reordered; prerequisite notes added |
| 11 | ⬜ sentinel convention unexplained | task_appraise | Fix | Live UI row now explains ⬜ inline |
8. Result
Meta-type: Auxiliary type with secondary MDI window. DB layer fully compliant (all checklist criteria met, verified in SQL task). Domain struct complete. Repository and service: CRUD present but count method missing throughout (repo → service → protocol → nats-handler route). Service missing NATS event publishing on save/delete; requires book_status_changed_event.hpp first (generated by eventing codegen). nats-eventing profile not yet run (book_status_changed_event.hpp absent; blocks event publishing and live-dropdown fix). nats-handler present but does not subscribe to changed event yet. Qt classes all generated; BookDetailDialog uses hardcoded statuses instead of fetching live from NATS. Shell and CLI not yet implemented. Manual not written.
Fixes needed (driving subsequent tasks):
- Add count to repo/service/protocol; also add nats-handler route for
count_book_statuses_request - Run nats-eventing codegen and generate
book_status_changed_event.hpp(prerequisite for item 3) - Add NATS event publish to service on save/delete (requires event type from item 2)
- Run messaging codegen (nats-handler); reconcile diffs
- Run Qt codegen; reconcile diffs
- Run SQL codegen; reconcile diff
- Fix
BookDetailDialog::populateBookStatusCombo()to fetch from service - Implement shell and CLI commands
- Write manual chapter