The entity specification (superseded)

Adding an entity touches the protocol for its operations, the endpoint for its routes, and the screens. It never touches another entity's code. If adding an entity requires editing shared, unrelated code, that shared code is missing an abstraction and fixing it is the first task.

• The plural noun as the page title, sentence case.
• One sentence saying what the collection is.
• Actions at the right: Refresh and Add (primary).

The Qt standard's action set, in its order, with its icons:

An entity may add its own actions after History. The accounts screen adds Lock, Unlock and Reset password there, which is the right place for an action that acts on the selection.

Opening a record is a click on the row. Edit exists for discoverability, not as the only way in.

The Qt client has no keyboard shortcuts. There should be here. Enter opens the selected record, Delete removes it, and the table is reachable from the keyboard. The omission is a gap, not a convention worth carrying.

• Columns come from a single declaration per entity, which is also what the renderer uses. One source, so a column cannot be styled differently from how it was declared.
• The Qt client has ten column styles and they are worth keeping, because they capture real distinctions: text_left, text_center, mono_left, mono_center, mono_bold_left, mono_right, mono_bold_center, icon_centered, icon_text_left, badge_centered.
• The display name is the first column and is the row's identity to a person.
• Selection is single. The accounts screen uses multi-selection, which is a legacy deviation; bulk operations are a separate feature with a separate design, not a table mode.
• Audit columns are hidden by default and available through the column menu; the set is in section 12.
• Column visibility and order are remembered per user, and the saved state is versioned so a change to the column set does not restore an incompatible layout.
• Sorting is available on every column. The default is the entity's natural order: name for reference data, most recent first for transactional data.

Two corrections to the Qt behaviour, both deliberate. The Qt client sorts on the displayed string, so a numeric column sorts lexically and 10 comes before 9; here, sorting uses the underlying value. And the Qt client declares a default column width that no code consumes, so columns are whatever the user last dragged them to; here the declaration is honoured.

Paging, with the count first, then First, Previous, Next, Last and Load all, then "Page size:" with a selector offering 25, 50, 100, 200 and 500, defaulting to

1. That is the Qt client's shape and it is kept.

Load all is offered only when the total is at or below 1000, which is the rule the Qt client already applies. Offering it for a hundred thousand records is a trap.

Changing the page size or page number resets to the first page, and a reload after a save returns to the first page rather than the page you were on. The Qt client documents this and it is right: the changed record may no longer be on the page you were looking at.

The Qt client has a feature worth keeping and worth explaining, because it is invisible until it fires. After a reload, rows whose recorded_at is newer than the time of the previous reload are highlighted, and the highlight pulses to draw the eye. On the first load there is no baseline, so nothing is highlighted.

The colour is a single gold, rgb(255, 215, 0), applied to the text rather than the background. The pulse runs six cycles at 500 ms. The point is that a person watching a live system sees what just changed without re-reading the table.

Worth carrying across, and worth making a setting, because a table that flashes on every update is worse than one that never does.

The Qt dialog is 600 by 700 with a minimum of 600 by 500. The root is a tab widget above a button row. The button row, in order, with its icons, is Delete (delete), Close (dismiss), Save (save), with Save as the default action.

A read-only toolbar appears above the tabs only when viewing a historical version, offering Revert to this version.

<Name of the record>                              [Save]
[ General ] [ <Field group> ] [ Related ] [ Provenance ]
 Field                Field
 Label                Label
 [______________]     [______________]
                                      [Delete]  [Close]

The generated standard emits one tab per field group declared for the entity, plus Provenance. The accounts dialog instead has six fixed tabs. The field-group rule is the standard because it is derivable from the model; the account's fixed tabs are not.

A tab that would be empty is not rendered.

Fields with nothing to show display "not recorded", so a blank is never mistaken for a failure to load.

• One label per field, above the control. The Qt labels carry a trailing colon, "Username:". Sentence case without the colon is the web convention and reads the same; this is a deliberate departure.
• A hint below the control when the field needs explaining.
• Required fields are marked, and the mark is described in words for a screen reader rather than being a bare asterisk.
• Read-only fields are visibly read-only. The Qt client disables them in some places and sets them read-only in others, inconsistently; read-only is the rule, and a disabled control is used only where a whole section is inactive.
• The key field is editable only when creating. The Qt rule is exactly right and applies to every entity: setReadOnly(!createMode). The username, the code, the natural key, is fixed once the record exists.
• The type or classification field is likewise disabled after creation, because changing what a record is changes what it means.
• Validation runs on blur, never on every keystroke, and never clears a message while the person is still typing the fix.
• A field with an error shows the message beneath it, and focus moves to the first field with an error on a failed submit. The Qt client has no inline errors at all and uses a modal warning; inline is better and is the standard here.

The Qt model declares a widget type per field, and the set is good because each implies its validation:

A field that is a foreign key is always a searchable select, never free text. Typos in keys are the most expensive kind of bad data.

Delete is not rendered in create mode. The Qt client disables it rather than hiding it; hidden is better, for the reason in section 11.

Closing with unsaved changes prompts: title "Unsaved Changes", text "You have unsaved changes. Close anyway?". That wording is exact and worth keeping.

• Creating an account prompts for no reason, and save_account_request has no audit fields to carry one.
• Deleting an account prompts for no reason.
• Editing an account prompts only when parties or roles changed. A change to the email, the full name or the job title is sent with empty audit fields, even though update_account_request has the fields.

So a person can change whose email an account uses, and the record will not say why. That is a defect, not a convention.

The service overwrites what it owns: the tenant, the actor, the timestamp, and the version. That is a security boundary and it means a client cannot forge them.

It does not mean a client may omit them or send an empty string. The request is decoded before any of the service's checks run, so a field that does not parse fails the whole request, and it fails as an unexplained refusal rather than as a validation error. A create, which has no tenant and no timestamp, must therefore send a tenant and a timestamp anyway — placeholders that parse, which the service then replaces.

This is worth stating because the failure mode is expensive: a missing field and a refused permission look identical from the client, and the difference is days of work.

Every create, amend and delete prompts for a reason, and the reason is stored. One dialog serves all three, and its wording follows the operation:

The dialog is at least 450px wide, offers the reason codes the server provides, and shows the selected reason's description beneath the selector in muted italic. The commit button is disabled until a reason is chosen.

This is the rule that matters most and is easiest to get wrong. One code, common.non_material_update, means "touched but nothing changed". For a create every reason is offered. For an amend or a delete:

• If fields were modified, the non-material reason is disabled, with the tooltip "Not available when fields have been modified".
• If no fields were modified, every other reason is disabled, with the tooltip "Only available when fields have been modified".

So a person cannot record a material change as a touch, nor a touch as a material change. The enabled set is a function of the diff, computed rather than trusted.

Some reason codes require an explanation. The label then reads "Commentary is required for this reason." and the field is marked required. Otherwise it reads "Commentary is optional for this reason."

Reasons belong to a category, and the entity's category selects which are offered: system for creation, common for amendment and deletion. The categories come from the server, not from a list in the interface.

The detail screen's Provenance tab is read-only and shows exactly six rows, in this order, with these labels:

Version, Modified By, Performed By, Recorded At, Change Reason, Commentary

The tab is disabled in create mode, because a record that does not exist has no provenance.

A horizontal split. On the left a timeline, on the right a diff.

• The timeline is 220-320px wide, headed "History Timeline", newest first. Each entry reads v<version> . <relative time>, with the full timestamp on hover, and below it the modifier, the performer, the reason code as a badge, and the commentary in italic. Clicking previews that version against its predecessor.
• The right pane is headed "Compare:", with two selects for the from and to versions and a control offering "All Fields" or "Only Changes". The diff uses line and span highlighting, so a changed span within a line is marked rather than only whole lines.
• Choosing a from version newer than the to version says "The From version must be older than the To version." Selecting the same version twice says "(No field changes)".
• The oldest version has nothing to compare against and shows "(Initial version)". A version with no differences shows "(No field changes)".
• Provenance fields are excluded from the diff and shown on the timeline entry only, because version and actor differ by definition and diffing them is noise.
• The toolbar offers Reload (arrow_clockwise), Open (edit) and Revert (arrow_rotate_counterclockwise). Open can be used with any selection; Revert only when the selection is not the current version.
• Reverting prompts: "Are you sure you want to revert '%1' from version %2 back to version %3? This will create a new version with the data from version %3." Reverting creates a new version; it never removes one.

Opening a version in read-only mode reopens the detail screen with Save and Delete hidden, a "Revert to this version" action shown, and the Security tab disabled. That is the right treatment and is kept.

A dropdown chevron is not from this set; it is the platform's own control.

An icon never appears alone where its meaning is not obvious. If removing an icon loses no meaning, remove it.

Every message says what happened and what to do next. "Error" alone is not a message. The Qt client's exact validation strings are worth keeping: "Username is required.", "Passwords do not match.". The server's own text is always preferred where there is any.

• An action the person may not perform is not rendered, rather than rendered and disabled. A disabled button invites a question a missing one does not.
• Permissions are decided by the server. The interface hides what the server would refuse and never attempts to be the authority.
• A refusal is shown as a refusal, not as a failure.

• A destructive action confirms first, and the confirmation says what will be lost. "Are you sure you want to delete account 'jdoe'?" is the shape.
• Deletion is soft wherever anything references the record, and the interface says which of the two it is doing. A deletion that removes history is a different action from one that does not, and they must not look the same.
• Reverting creates a new version. It never removes one, and the confirmation says so.

version, modified_by, performed_by, recorded_at, change_reason_code, change_commentary, tenant_id, and description on every entity.

id is never shown and never offered, because nobody reads a UUID. It is available through a copy action on the detail screen.

The Qt client hides description on every entity by rule and the audit fields by declaration. Same result, and the rule is worth keeping.

1. Confirm it is an entity. It has all six properties in section 2. If it does not, say so and agree the exception before proceeding.
2. Classify it. Reference or transactional. Lookup or free-form. Temporal or not. That decides its columns, its sort order, and whether history exists.
3. Name the collection and the display field.
4. Group its fields. Each group becomes a tab. A group with one field is usually a mistake.

1. Add the request and reply schemas for list, save, delete and history.
2. Add the subjects.
3. Prove a round trip against the running service, using a rejected or empty case as well as a good one, because a well-formed rejection proves the wire format where a success might not.

1. Add the routes: list, get, create, update, delete, and history where it applies.
2. Validate every input at the boundary and map every failure to a status.
3. Assert that no field the entity marks as secret appears in any response.

1. Declare the columns once.
2. Build the list screen from the shared shell, including search and the type filter.
3. Build the detail screen with the field-group tabs and Provenance.
4. Build the history screen where the entity is temporal.
5. Wire the audit prompt into save and delete, including the diff-driven reason filter.

1. Drive the real screens in a browser: list, search, filter, open, create, edit, delete, and history where it exists.
2. Assert the states that are easy to forget: empty, filtered-empty, error, loading with existing data, and unauthorized.

1. Add the entity to the navigation.
2. Record anything about this entity that would surprise the next person.