@nocobase/app-skills 0.1.0-beta.43 → 0.1.0-beta.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.43",
3
+ "version": "0.1.0-beta.44",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -60,7 +60,7 @@ For approval requirements, check `@nocobase/app-plugin-approval` first. If missi
60
60
 
61
61
  When the stages of a business record are fixed by developers rather than drawn by administrators — an expense report, a ticket, a contract, an order — build it with `@nocobase/lifecycle` as [record lifecycles](references/lifecycle.md) describes: the state stays in the record's own field and changes only through declared transitions. Declare only required business paths with precise sources and destinations; the diagram expands every `from × to` pair rather than analyzing routing logic. Follow [readable process graphs](references/lifecycle-ui.md#keep-process-graphs-readable) before rendering dense definitions.
62
62
 
63
- For notification configuration or sending, follow the notification plugin Skill: `notification.channels` maps each name to one flat Provider configuration, and `send({ idempotencyKey, messages })` supplies a complete message per Channel. Use native addresses; email and in-app arrays create independent deliveries, while Webhooks forbid `to`.
63
+ For notification configuration or sending, follow the notification plugin Skill: `notification.channels` maps each name to one flat channel configuration with `type` (`provider` remains a compatibility alias), and `send({ idempotencyKey, messages })` supplies a complete message per Channel. Use native addresses; email and in-app arrays create independent deliveries, while Webhooks forbid `to`.
64
64
 
65
65
  Install, update and customize plugins, and remove a direct NocoBase package, as [plugins](references/plugins.md) describes: `pnpm nocobase plugin register`, `plugin update` and `package remove` keep the manifest, the lockfile, the composition roots and the synchronized Skills consistent, so never hand-edit only one of them.
66
66
 
@@ -86,7 +86,9 @@ Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is
86
86
 
87
87
  ## Include administration by default
88
88
 
89
- For every application feature, apply [system settings delivery](references/system-settings.md): keep a newly created, Home-only application free of settings; as the application develops beyond that basic shell, reconcile the template's prepared Users and Roles and permissions routes and the management surfaces for each capability actually used. Inspect this on every build or iteration, enable missing routes once and preserve already enabled pages, including workflow definitions, diagrams, configuration and authorized execution history. When building process rules, proactively declare appropriate thresholds and reviewer choices as validated, authorized business parameters and provide visible parameter forms in workflow management, with optional diagram-bound shortcuts to the same editor; the user need not ask for configurability. Apply the same check to non-workflow business policy, mutable dictionaries, business document numbering, important operation records and the other used capabilities in that reference. Follow its [business administration recipes](references/business-administration.md) for application-owned implementations and acceptance. The real execution must consume the saved values; source/deployment configuration retains its owner. This is part of implementing the feature, not a separate user request.
89
+ For every application feature, apply [system settings delivery](references/system-settings.md): keep unused business settings disabled in a newly created application while retaining its restricted App Foundation entry; as the application develops beyond that basic shell, reconcile the template's prepared Users and Roles and permissions routes and the management surfaces for each capability actually used. Inspect this on every build or iteration, enable missing routes once and preserve already enabled pages, including workflow definitions, diagrams, configuration and authorized execution history. When building process rules, proactively declare appropriate thresholds and reviewer choices as validated, authorized business parameters and provide visible parameter forms in workflow management, with optional diagram-bound shortcuts to the same editor; the user need not ask for configurability. Apply the same check to non-workflow business policy, mutable dictionaries, business document numbering, important operation records and the other used capabilities in that reference. Follow its [business administration recipes](references/business-administration.md) for application-owned implementations and acceptance. The real execution must consume the saved values; source/deployment configuration retains its owner. This is part of implementing the feature, not a separate user request.
90
+
91
+ For initialization prerequisites introduced by the feature, apply [setup readiness](references/setup-readiness.md): wire real required-role membership and applicable business relationship checks with the standard contextual hint. Users should see what configuration is missing and an authorized path to fix it. Installed plugins, read failures and missing business configuration are different states; keep the bare app and its protected App Foundation entry unchanged.
90
92
 
91
93
  ## Frontend work
92
94
 
@@ -340,14 +340,15 @@ When the response is not 2xx, `api.request` throws `ApiClientError`:
340
340
 
341
341
  Write the checks directly in the component that uses them (for example `ProjectSummary` above and `CompleteProjectButton` below); extract them only when several pages share them (["Basic conventions" in `../frontend-dev.md`](../frontend-dev.md#basic-conventions)).
342
342
 
343
- | Case | Check | Handling |
344
- | -------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
345
- | Session ended | `error instanceof ApiClientError && error.status === 401` | The session expired or was revoked: no Retry; offer "Sign in again" where the error shows (below the table) |
346
- | Record not found | `error instanceof ApiClientError && error.status === 404` | Say the record does not exist or has been deleted, offer a next step (close the overlay, go back to the list) and refresh the list; no retry (guideline R3) |
347
- | No permission | `error instanceof ApiClientError && error.status === 403` | Say the user does not have permission; no retry (guideline S4) |
348
- | Business error reason | `error instanceof ApiClientError && error.reason === 'PROJECT_NAME_TAKEN'` | Show it below the matching field with `form.setError(...)`; see [`form.md`](form.md) |
349
- | Conflict | `error instanceof ApiClientError && error.status === 409 && error.reason === 'VERSION_CONFLICT'` | Keep the input and offer "Load latest", not Retry (below the table) |
350
- | Other (network, 5xx, etc.) | None of the above | Say "The request failed. Please try again."; when loading data, offer "Retry" |
343
+ | Case | Check | Handling |
344
+ | -------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
345
+ | Session ended | `error instanceof ApiClientError && error.status === 401` | The session expired or was revoked: no Retry; offer "Sign in again" where the error shows (below the table) |
346
+ | Record not found | `error instanceof ApiClientError && error.status === 404` | Say the record does not exist or has been deleted, offer a next step (close the overlay, go back to the list) and refresh the list; no retry (guideline R3) |
347
+ | No permission | `error instanceof ApiClientError && error.status === 403` | Say the user does not have permission; no retry (guideline S4) |
348
+ | Invalid input or filters | `error instanceof ApiClientError && error.status === 400` | Explain which input or filter needs correcting when known; preserve the input and provide a correction path instead of retrying the unchanged request. Never show raw server messages. |
349
+ | Business error reason | `error instanceof ApiClientError && error.reason === 'PROJECT_NAME_TAKEN'` | Show it below the matching field with `form.setError(...)`; see [`form.md`](form.md) |
350
+ | Conflict | `error instanceof ApiClientError && error.status === 409 && error.reason === 'VERSION_CONFLICT'` | Keep the input and offer "Load latest", not Retry (below the table) |
351
+ | Other (network, 5xx, etc.) | None of the above | Say "The request failed. Please try again."; when loading data, offer "Retry" |
351
352
 
352
353
  - **Conflict (409)**: a write the server rejects because the record changed after it was loaded (reason `VERSION_CONFLICT` from a Repository write, or your endpoint's own conflict reason). Keep the input, say that someone else changed the record, and offer "Load latest" (reload the record, then let the user reapply the change) rather than "Retry", which would fail again (guideline R1).
353
354
  - **Session ended (401)**: a loader, form or dialog renders `SessionExpiredAlert` ([`example/session-expired-alert.md`](example/session-expired-alert.md)); a single-click write puts the same button in the toast's `action`. The button calls `refresh()` from `useAuthentication()` (`@nocobase/app-plugin-authentication/client`). While it runs, `AuthenticationGuard` renders nothing, so the signed-in pages and their input unmount, and `RequiredAuthentication` then sends the user to sign in. That is why the user starts it: never call `refresh()` from an effect or a `catch` on your own.
@@ -120,7 +120,7 @@ Check them in the order "failed → first load → empty → data or no results"
120
120
  ## 8. Column definitions and row actions
121
121
 
122
122
  - Create `columns` with `useMemo`, and put everything it uses (`t`, the formatters, `location.search`) in the dependency array.
123
- - **The first column is the name** (guideline T1.3), a `Link` to the detail child route: `to={{ pathname: row.original.id, search: location.search }}`. The path is relative and keeps the query parameters, so closing the detail view returns to the same filtered result.
123
+ - **The first column is the name** (guideline T1.3), a `RecordLink` from `#components/record-link` to the detail child route: `to={{ pathname: row.original.id, search: location.search }}`. The path is relative and keeps the query parameters, so closing the detail view returns to the same filtered result.
124
124
  - **Sortable columns** (guideline T1.8): make every date and time column (created, updated, due) and every number column sortable without being asked, and the name column when it sorts in the current language's order. Leave statuses, types, tags, people, long text and yes/no values as plain titles unless the business asks for them and the order means something.
125
125
  - A sortable column uses `DataTableColumnHeader` as its `header` and sets `enableHiding: false` (see [section 3](#3-known-datatable-behavior)); a plain column uses the translated text directly. In a server-paginated list, the endpoint must accept the column in `orderBy`.
126
126
  - Sorting Chinese names in the browser: `sortingFn` compares with `Intl.Collator(locale)`.
@@ -129,7 +129,7 @@ Check them in the order "failed → first load → empty → data or no results"
129
129
  - **Format times in the current language** (guideline T1.6): get `locale` from `useLocale()` and create the `Intl.DateTimeFormat` with `useMemo`, so it updates when the language switches.
130
130
  - **Right-align numbers** (guideline T1.6): `DataTable` has no per-column alignment option, so align inside the header and the cell, in a `div` (`text-right` does nothing on an inline `span`): `header: () => <div className='text-right'>{t('projects.fields.budget')}</div>` and `cell: ({ row }) => <div className='text-right tabular-nums'>{amountFormat.format(row.original.budget)}</div>`, with `amountFormat` an `Intl.NumberFormat` created in `useMemo` from `locale`. For a sortable number column, pass the alignment to the header itself, with no wrapper: `<DataTableColumnHeader column={column} title={…} className='justify-end text-right' />` (its root is a flex row when the column sorts and a plain `div` when it does not, so both classes are needed). The sort button keeps its padding, so the title sits slightly left of the numbers.
131
131
  - **Show a cut-off cell's full content on hover** (guideline T1.11): a cell does not wrap and the table widens to fit it, so content is cut off only where a column limits its width. There it ends in an ellipsis, and hovering shows the full value, but only when it is cut off:
132
- - Text, or a link such as the name column, uses a `Tooltip` whose trigger is the truncated element; `TooltipTrigger` leaves a `Link` a link. `onOpenChange` cancels the tooltip when the value fits:
132
+ - Text, or a link such as the name column, uses a `Tooltip` whose trigger is the truncated element; `TooltipTrigger` leaves a `RecordLink` a native link. `onOpenChange` cancels the tooltip when the value fits:
133
133
 
134
134
  ```tsx
135
135
  <Tooltip
@@ -143,7 +143,7 @@ Check them in the order "failed → first load → empty → data or no results"
143
143
  >
144
144
  <TooltipTrigger
145
145
  render={
146
- <Link
146
+ <RecordLink
147
147
  to={{ pathname: row.original.id, search: location.search }}
148
148
  className='block max-w-60 truncate'
149
149
  />
@@ -155,7 +155,7 @@ Check them in the order "failed → first load → empty → data or no results"
155
155
  </Tooltip>
156
156
  ```
157
157
 
158
- For plain text, render `<span className='block max-w-60 truncate' />` in place of the `Link`.
158
+ For plain text, render `<span className='block max-w-60 truncate' />` in place of the `RecordLink`.
159
159
 
160
160
  - A `Badge` or other styled content goes in a `Popover` that opens on hover (`openOnHover delay={0}` on the trigger) instead: the tooltip surface is inverted, so a badge on it is unreadable.
161
161
  - `truncate` shows the ellipsis only on a block element. On a flex element such as `Badge` it clips without one, and the centered text loses both ends, so put the text in a `<span className='truncate'>` inside the badge and give the badge `min-w-0 shrink`. Do not use `line-clamp` in a cell: it needs text that wraps, which the cell prevents, so it only clips.
@@ -245,3 +245,7 @@ Try it by hand in a browser; static checks cannot find input method and focus pr
245
245
  - The date and number columns sort, and a server-paginated list keeps the sort in the URL and starts it on the first page.
246
246
  - Delete a record in the detail drawer: after the list refreshes, focus is on the search box.
247
247
  - At a width of 375px, the toolbar wraps and the table scrolls horizontally; everything is legible in both the light and dark themes (guidelines A4 and F6).
248
+
249
+ ### Restore list position
250
+
251
+ The template's `#hooks/use-table-url-state` adapts standard `DataTable` controlled pagination/sorting to `page`, `pageSize`, `sort` and `order` query parameters. Pass an explicit allowlist of sortable column IDs. Use it with `RoleList.tableState` or spread its result into `DataTable`; server lists also set `manualPagination`/`manualSorting` and send those values to the real API. Supply `rowCount` only for the current successful query, never cached rows during loading/errors. Client lists retain the full dataset for the table's local sorting/paging. Filter changes reset `page` while preserving unrelated URL context, page size and ordering. Links to child details carry `location.search` and close to the same view. Test reload/history and removal of the last row on a page. A controlled table delegates page resets to the host so refreshed data cannot silently jump back to page one.
@@ -153,9 +153,9 @@ A role administration table built with the standard DataTable: localized column
153
153
  - Install: `yes n | pnpm exec shadcn add @nocobase/role-list`
154
154
  - Installs to: `client/components/role-list.tsx`
155
155
  - Plugin dependencies: none
156
- - Also installs: `@nocobase/data-table`
156
+ - Also installs: `@nocobase/data-table`, `@nocobase/record-link`
157
157
  - Example: `@nocobase/role-list-demo` (`pnpm exec shadcn view @nocobase/role-list-demo`)
158
- - After installing: Render inside a React Router and the application i18n provider. Supply roles with key, localized title, edit destination (to) and protected state. Pass localized labels for name, key, type, protected and custom, plus an optional ariaLabel. Uses the shared DataTable for table semantics, sorting and pagination. The host owns loading, empty/error states, filtering and authorization. Existing apps must update the installed role-list component, its data-table dependency and caller labels together.
158
+ - After installing: Render inside a React Router and the application i18n provider. Supply roles with key, localized title, edit destination (to) and protected state. Pass localized labels for name, key, type, protected and custom, plus an optional ariaLabel. Uses the shared DataTable for table semantics, sorting and pagination. Optional tableState accepts controlled pagination/sorting and page-size choices from the host URL adapter. The host owns loading, empty/error states, filtering and authorization. Existing apps must update the installed role-list component, its data-table dependency and caller labels together.
159
159
 
160
160
  ### default-access-editor
161
161
 
@@ -170,6 +170,17 @@ Controlled default data scope rule fields with business-object selection, indepe
170
170
 
171
171
  ## Data display
172
172
 
173
+ ### record-link
174
+
175
+ A native router link for record names and identifiers in tables and lists: foreground text at rest, underline on hover and visible keyboard focus. Preinstalled in both application templates.
176
+
177
+ - Kind: component
178
+ - Install: `yes n | pnpm exec shadcn add @nocobase/record-link`
179
+ - Installs to: `client/components/record-link.tsx`
180
+ - Plugin dependencies: none
181
+ - Example: `@nocobase/record-link-demo` (`pnpm exec shadcn view @nocobase/record-link-demo`)
182
+ - After installing: Render inside a React Router and pass the record route through to. Carry the current list query in to.search when opening a child route. Supports native Link props and refs; use action buttons and menu items separately.
183
+
173
184
  ### kanban
174
185
 
175
186
  A generic board: columns of cards dragged within and between columns, reporting each move through a callback. Use it for any board view, such as issues by status from @nocobase/app-plugin-projects.
@@ -349,6 +360,17 @@ A settings dialog after shadcn's sidebar-13: grouped categories in a sidebar on
349
360
  - Example: `@nocobase/settings-dialog-demo` (`pnpm exec shadcn view @nocobase/settings-dialog-demo`)
350
361
  - After installing: Pass groups of { id, label, icon } items, the activeId and onSelect (or renderItem to draw each entry as a router link), and render the open entry as children, optionally in a SettingsDialogSection. Every word comes from the props; the component ships no locale keys.
351
362
 
363
+ ### setup-readiness
364
+
365
+ Contextual prerequisite checks for a feature, with missing, ready and unavailable states. Connect real authorized business reads; never infer readiness from installed plugins. Preinstalled in application templates.
366
+
367
+ - Kind: component
368
+ - Install: `yes n | pnpm exec shadcn add @nocobase/setup-readiness`
369
+ - Installs to: `client/components/setup-readiness.tsx`, `client/components/setup-readiness-state.ts`
370
+ - Plugin dependencies: none
371
+ - Example: `@nocobase/setup-readiness-demo` (`pnpm exec shadcn view @nocobase/setup-readiness-demo`)
372
+ - After installing: Memoize SetupCheck descriptors and the async inspect callback; wire useSetupReadiness to the feature’s authorized aggregate read and pass its state to SetupReadiness. Supply translated labels, stable ids and authorized configuration links. No checks or disabled inspection causes no reads. Refresh on the host route key and after configuration saves; focus rechecks mounted checks. Unknown reason is unavailable, signIn, forbidden or invalid. Only missing checks render configuration links; denied/invalid reads are not missing. Initial all-ready hides; explicit refresh keeps a compact confirmation and the refresh control. This is informational; execution still validates prerequisites server-side. Templates also include RequiredRoleSetup for explicitly declared business roles.
373
+
352
374
  ## Projects
353
375
 
354
376
  ### issue-table
@@ -56,7 +56,7 @@ Structure, top to bottom: PageHeader (primary action "New X") → toolbar (searc
56
56
 
57
57
  - **T1.1 [Must]** The search box has a placeholder that says which fields it searches, for example "Search by name or email".
58
58
  - **T1.2 [Must]** Filter controls show their current value; while a search or filter is applied, show "Clear filters".
59
- - **T1.3 [Must]** The first column is the record's name or number; when there is a detail view, clicking it opens the detail view.
59
+ - **T1.3 [Must]** The first column is the record's name or number; when there is a detail view, clicking it opens the detail view. Use the template’s `RecordLink` for record names and identifiers: foreground text with medium weight, no permanent underline, underline on hover, and underline plus a visible focus outline for keyboard navigation. Preserve native link behavior; action buttons and menu items keep their own styling.
60
60
  - **T1.4 [Must]** Enumerated values such as status and type are shown as text in a Badge; color is only an aid, and values must never be distinguished by color alone.
61
61
  - **T1.5 [Must]** A row's actions sit at the end of the row behind one icon-only ghost "…" button (`MoreHorizontalIcon`, `size='icon-sm'`, labelled "Actions for <name>") opening a `DropdownMenu`. Destructive items come last, after a `DropdownMenuSeparator`, with `variant='destructive'`, and are confirmed with an AlertDialog (I2). A table whose rows have exactly one non-destructive action may show it as a single ghost button instead, the same way on every row.
62
62
  - **T1.6 [Must]** Dates and times are formatted for the current language; numbers and amounts are right-aligned, with thousands separators.
@@ -65,6 +65,7 @@ Structure, top to bottom: PageHeader (primary action "New X") → toolbar (searc
65
65
  - **T1.9 [Must]** A list page must have a design for all four states S1–S4.
66
66
  - **T1.10 [Must]** When a list shows only part of the matching results, because it sorts and paginates one capped page in the browser or because the endpoint returns no total, show a notice when the results reach the cap ("Only the first N records are shown. Use search or filters to narrow the results."); records beyond the cap must not silently disappear.
67
67
  - **T1.11 [Must]** When a table cell is too narrow for its content, the content ends in an ellipsis where it is cut off, and hovering over it shows the full content. Content that fits shows nothing on hover.
68
+ - **T1.12 [Must]** Pagination labels size to their localized text rather than a fixed English-sized width. Keep each short page summary, page-size control and navigation button group intact; at narrow widths, wrap whole groups onto another row instead of splitting labels or shrinking controls. Verify Chinese and English with large page counts at 375px and desktop widths.
68
69
 
69
70
  ### T2 Detail view
70
71
 
@@ -71,6 +71,10 @@ React Flow needs a definite sized ancestor; min-height alone inside unconstraine
71
71
 
72
72
  Fit the full graph, including outer edge routes and labels. Prefer top-to-bottom direction for tall details, readable spacing, subdued ordinary edges and labels on their routes. Give the current node a strong marker and actual history lighter highlights, retaining the diagram's textual status and icons. Keep current state, visited path and available actions distinct; infer no traversed edge from reachable states or endpoints alone. Use the shared theme tokens and translated accessible labels.
73
73
 
74
+ For compact business diagrams, prefer `presentation="process"` on the existing `LifecycleDiagram`; use `stateKind` to supply application-owned approval, work and outcome semantics while preserving configuration and history behavior. The classic presentation remains available by default. Process mode omits backward and self-transitions from the canvas, including adjacent returns that may become long loops, and shows their action and source/target explanation beside the hovered or focused endpoint; keep state declaration order aligned with forward progress. Execution history lists remain complete even when a long return line is omitted. For custom adapters, use the shared `FlowDiagram` capabilities (`direction="DOWN" compact controls`) and `FlowDiagramStep` from `@nocobase/flow-diagram`: start/outcome pills, approval/work cards, explicit current/visited/unreached status, multiline conditions, fullscreen and a shape-aware overview. Set `bare` and fixed dimensions on custom nodes and provide translated labels, icons, arrival summaries and authorized configuration actions through props. Keep business classification and policy bindings in application adapters; do not copy a list of OA-specific state or transition names into shared components.
75
+
76
+ Definition overviews select the main business path in their adapter and show return, retry and self-transition explanations through `FlowDiagramTransitionNotes` beside the hovered or focused node: one card with Leaves to and Arrives from sections that lists each transition once per direction with the states at the other end, while `auxiliaryEdges` outlines those states. Do not use `revealEdges` for standard process overviews: it draws auxiliary lines and can reintroduce long loops. Use `renderNode(node, { active })` for additional exit explanations, including where an undrawn state continues or ends. Keep branch conditions visible, show full action text through `title`, and use `faint`/`dashed` for secondary routes. Execution views retain every actual recorded transition, including returns and exceptional outcomes, and derive visited status from authoritative history. Keep page scrolling available over the canvas; use explicit zoom/fit controls. Fullscreen provides an overview and exits with Escape.
77
+
74
78
  ## Execution detail
75
79
 
76
80
  Identify workflow and business record in the title with a compact, labeled refresh action. Place a large diagram card beside a stack of History, Effects and recorded parameter information; stack on narrow screens. items-stretch can align the diagram with a taller history column when the canvas has a supported height.
@@ -0,0 +1,93 @@
1
+ # Show missing prerequisites where they matter
2
+
3
+ As a feature is developed, connect its actual initialization prerequisites automatically, even when the user does not ask for a setup checklist. Declare checks when implementing the business feature, using the owning service's real authorized reads. The template does not infer arbitrary roles or manager relationships at runtime. An installed plugin or a Foundation capability marked registered is not evidence that a business process is ready. Reuse Foundation for capability evidence; do not build another plugin inventory or amend Foundation's status from guessed business requirements.
4
+
5
+ ## What belongs in a check
6
+
7
+ Check only what the current feature consumes: an enabled member assigned to a required business role, an employee's direct manager when submission requires one, or an administrator-owned routing rule the service actually reads. Do not check all registered roles, all users or every installed plugin. A bare application has no business prerequisites; it shows no setup banner and starts no setup reads. Keep the existing restricted App Foundation entry. API-only delivery and explicit scope exclusions retain their meaning.
8
+
9
+ Ship a compact hint above the dependent feature or within its existing management page. Name the missing item and the effect, for example “Finance reviewer: assign an enabled member before high-value requests can be reviewed.” Show an authorized link to the exact configuration, not a generic Settings link. Ordinary employees see only their own relevant reason; an administrative checklist may show authorized aggregate counts. Never reveal another employee's manager, a roster, credentials or raw server errors merely because they can see a process definition. Do not add a global setup wizard, dashboard or menu just to host checks.
10
+
11
+ Read checks on entering the feature, after a successful configuration save, on returning from configuration and on window focus. Refresh the host and its checks together when the host offers Refresh. Use a bounded aggregate query for business relationships, not a query per user or per table row. Do not run checks in app startup, block unrelated pages, poll, or perform a separate full-app scan after every code change. Reconcile only the affected feature's declarations during implementation.
12
+
13
+ ## Standard template parts
14
+
15
+ Both templates include `SetupReadiness` and `useSetupReadiness` in `#components/setup-readiness` and `#components/setup-readiness-state`. They are also the `@nocobase/setup-readiness` UI Registry entry, not an npm package. `SetupReadiness` renders localized labels supplied by its host. Memoize the check descriptors and inspection callback. Pass a stable id for each check and `refreshKey: location.key` for a mounted parent that survives child configuration navigation. Explicitly call the hook's `refresh` after a successful inline save. An empty declaration or `enabled: false` performs no inspection. Use a key based on the inspected business subject if reusing the same component across unrelated subjects.
16
+
17
+ An inspection returns a map keyed by the declared ids, each containing `{ status: 'ready' | 'missing' | 'unknown' }`. Unknown uses a safe `reason`: `unavailable` for transient failure, `signIn` for 401, `forbidden` for 403, `invalid` for an absent/incompatible declaration or 400/404. `setupInspectionFailure(error)` maps transport failures without exposing their text. Omitted results are invalid, never ready. Preserve successful independent results if another check fails. A missing item may supply an authorized action; `{ canConfigure: false }` suppresses it. Unknown never renders a guessed configuration link. Transient errors offer Check again; access denial, expired sign-in and invalid declarations explain their distinct next step. The control can still recheck other applicable items. Initial all-ready hides; after an explicit check a compact confirmation retains the refresh control instead of removing keyboard focus. This is not proof that the entire application is configured.
18
+
19
+ ### Required business role members
20
+
21
+ Use the preinstalled `RequiredRoleSetup`, which inspects real Users metadata and enabled-member totals using the exact role scope and role. It requests metadata once and one bounded page per distinct role, independent of the business table's search, filters or pagination. Authenticated-default permissions apply separately: the scope-level `hasAuthenticatedDefaultAccess` flag does not make its direct roles uncheckable or imply that everyone holds a selected business role. It does not assign roles. Read access is checked for `user:*:read`, and a member-management link additionally requires `user:*:assign-role`; the server remains authoritative. Nonassignable roles have no assignment action. Unknown roles/scopes, default-only roles absent from the selectable direct-role options, malformed responses and failed reads are indeterminate rather than empty.
22
+
23
+ ```tsx
24
+ import { useMemo } from 'react';
25
+ import { RequiredRoleSetup } from '#components/required-role-setup';
26
+
27
+ // Inside the real workflow definition or dependent feature page, after declaring
28
+ // the actual application-owned role and enabling the existing Users route:
29
+ const roles = useMemo(
30
+ () => [
31
+ {
32
+ scope: actualRoleScope,
33
+ role: actualFinanceRole,
34
+ title: t('expenseSetup.financeReviewer'),
35
+ description: t('expenseSetup.financeReviewerNeeded'),
36
+ },
37
+ ],
38
+ [actualRoleScope, actualFinanceRole, t],
39
+ );
40
+
41
+ return (
42
+ <>
43
+ <RequiredRoleSetup roles={roles} />
44
+ {/* Existing definition and configuration UI. */}
45
+ </>
46
+ );
47
+ ```
48
+
49
+ For an inline configuration save or host refresh that does not navigate, change the `RequiredRoleSetup` `refreshKey` prop after the save succeeds; route return and window focus are already connected. Use actual declared role constants and translated business labels. Do not paste an invented `finance` or `app` identity into an unrelated application. Ensure `/settings/users` is enabled once under existing settings; adapt `requiredRoleSetupLink` if the application's established Users path differs. The standard link includes both `roleScope` and `role`, `status=enabled` and a validated app-relative `returnTo` carrying the source query and hash. `returnTo` is routing context, not authorization, and never preselects or assigns a role to a new user. Use this adapter only when the business requires direct members of the selected scope. If reviewer resolution accepts group, inherited or department assignments, inspect its real resolver through a business-owned aggregate instead of treating a zero direct-member count as no eligible reviewers. Do not treat roles alone as a complete approval check: an enabled member may still lack a required business permission or a specific employee relationship.
50
+
51
+ ### Direct manager and other application-owned relationships
52
+
53
+ Implement the check in the existing application service that owns the relationships; use that same source in submission/execution validation. Do not invent a generic template `users.managerId`, create a second organization model or interpret a demo's fixed people as real users. If an installed plugin supplies the relationship, use its documented service and authorized API.
54
+
55
+ The administrator read should return a bounded aggregate, such as a count of enabled submitting employees with no valid enabled direct manager, computed with a fixed number of queries. Use the actual employee role, active status, relationship validity and tenancy/data scope. An unassigned department head, self/cyclic manager, disabled/deleted manager or relationship excluded by the execution rules must follow those same rules; do not count a nonempty string as valid. Normal employees receive only a current-user check. Never expand the read scope to make a setup banner work. Document the read permission and response through the real OpenAPI route. If such a read is unavailable, implement it with the business feature or report an unknown/unsupported check; do not fabricate a ready result.
56
+
57
+ Wire that real read to the standard hook:
58
+
59
+ ```tsx
60
+ // `readSetup` calls the authorized aggregate endpoint implemented in this feature.
61
+ // `checks` are memoized { id, title, description, action } descriptors; actions
62
+ // link only to existing authorized relationship configuration with returnTo.
63
+ const inspect = useCallback(async () => {
64
+ const setup = await readSetup();
65
+ if (
66
+ !Number.isSafeInteger(setup.missingManagerCount) ||
67
+ setup.missingManagerCount < 0
68
+ )
69
+ return { directManager: { status: 'unknown', reason: 'invalid' } } as const;
70
+ return {
71
+ directManager: {
72
+ status: setup.missingManagerCount > 0 ? 'missing' : 'ready',
73
+ },
74
+ } as const;
75
+ }, [readSetup]);
76
+ const state = useSetupReadiness(checks, inspect, {
77
+ enabled: canReadSetup,
78
+ refreshKey: location.key,
79
+ });
80
+ // Render <SetupReadiness state={state} labels={localizedLabels} />.
81
+ // The server validates response counts; reject malformed responses as unknown.
82
+ // After an inline relationship save, refresh both the host and state.refresh().
83
+ ```
84
+
85
+ Validate business response shapes before returning ready. If combining several sources, use per-check error handling with `setupInspectionFailure` to keep other successful results. Inspect saved server state rather than drafts or hardcoded defaults. For employees who cannot inspect administrative configuration, use the current-user API and actionable submission error; do not call global Users to infer a manager.
86
+
87
+ ## Delivery and upgrade checks
88
+
89
+ - Run the actual missing → configure → save → return → ready flow, plus a later removal/disable → missing flow. Distinguish a role with no enabled explicit members from a failed read or an unsupported default-membership policy.
90
+ - Verify initial ready, loading, network failure, 401, 403, unknown declaration, stale response and permission revocation; no stale success, raw error details or unauthorized configuration controls. Preserve other successful results on partial failure.
91
+ - Check a normal employee, a read-only administrator and an administrator allowed to configure. Direct API execution must still reject a missing prerequisite; UI hints never replace server validation, role scope enforcement or approval invariants.
92
+ - Preserve existing roles, grants, manager mappings and all business data. Checks only read; never seed demo members, assign fallback reviewers or grant roles automatically. Repeat inspection and configuration retries without duplicate writes.
93
+ - On template upgrade merge the shared implementation, retain custom business adapters, and reconcile declarations only for capabilities actually used. Upgrading provides the standard parts; it cannot identify a custom manager model or safely invent missing business checks. When adapting an old page, wire its existing service and entry rather than overwriting it.
@@ -1,10 +1,10 @@
1
1
  # Deliver system settings with the capability
2
2
 
3
- A usable application includes administration for the capabilities it uses. Do not wait for the user to request a separate settings page, workflow definition screen or execution history. Apply this rule throughout application development, based on the capabilities actually being built or used, regardless of the iteration number. On every build or change, inspect the current application and reconcile any missing administration. Creating or booting a bare Home-only application does not trigger settings. Respect an explicit request to omit a surface.
3
+ A usable application includes administration for the capabilities it uses. Do not wait for the user to request a separate settings page, workflow definition screen or execution history. Apply this rule throughout application development, based on the capabilities actually being built or used, regardless of the iteration number. On every build or change, inspect the current application and reconcile any missing administration. Creating or booting a bare application does not trigger unused business settings; retain the existing restricted App Foundation entry. Respect an explicit request to omit a surface.
4
4
 
5
5
  ## Baseline
6
6
 
7
- A newly created Default application shows Home only and does not register a System settings group or its routes. The template includes reusable application-owned Users and Roles and permissions page modules, ready to enable as the application develops. Examples is already a built application and registers them.
7
+ A newly created Default application shows Home and the existing protected System settings → App Foundation entry for an unrestricted administrator. Other users do not see that entry. It does not enable business settings or their prerequisite checks merely because plugins are installed. The template includes reusable application-owned Users and Roles and permissions page modules, ready to enable as the application develops. Examples is already a built application and registers them.
8
8
 
9
9
  As business capabilities are developed, automatically supply core user and permission administration and any management surfaces those capabilities need. If the core settings routes are still absent, import `systemSettingsRoutes` from `./pages/settings/routes.js` in `client/routes.ts` and append it once to the exported route contribution array: `const routes: readonly AppClientRouteContribution[] = [appRoutes, systemSettingsRoutes]`. Reuse an existing registration instead of duplicating it. If System management already exists, register the contribution's child routes with `parent: 'systemManagement'` (using the existing group's actual name), instead of registering a second settings group so Users, Roles and permissions, Workflow management and other administration entries appear together while retaining their URLs and permission ids. Do not make the user ask for user or permission settings separately, and do not grant access to ordinary users as a side effect. Existing applications that predate these modules should install or build equivalent real management pages as part of the current development task when needed. Preserve already enabled pages and their server authorization on every iteration. Do not use a first-build flag, a one-time setup stage, or the number of development rounds as the trigger. Reuse UsersClient and AuthorizationClient; the plugins own accounts, role scopes, grants, protected sets and their invariants. Keep personal account and appearance controls in the existing account/header surfaces.
10
10
 
@@ -16,6 +16,12 @@ For each applicable capability, identify its owner, persistence, authorized read
16
16
 
17
17
  Reconcile only missing pieces using stable route, group, field and resource keys. Preserve existing configuration, schemas, administrator grants, references and history. A later feature adds its own missing settings without resetting previous settings. Explicit API-only scope or a request to omit an interface still takes precedence.
18
18
 
19
+ The prepared Users list uses plain user names and one Edit entry for basic information and role assignments in a single `RouteDrawer`; do not add a separate details entry or stack an edit dialog above it. Expose the high-frequency Edit action directly on each row; keep Disable (Enable for a disabled account) and Revoke sessions in the More menu. Gate every action by its own permission and hide an empty More menu. Roles use a searchable single/multiple-selection dropdown rather than a long switch list. The editor has one Save: submit profile fields and changed role scopes atomically through `UsersClient.update`; never simulate this with sequential writes or provide competing Save buttons. Role-only managers can edit assignments while profile fields stay read-only; protected options and role-removal confirmation remain enforced. New-user creation stays a dialog and uses the same role picker. Preserve route and permission IDs; legacy detail URLs redirect to Edit. Resolve close/cancel destinations from the actual route hierarchy and preserve the list query, including when mounted at `/users` instead of `/settings/users`. Test both mounts, direct/legacy entry, combined saves, failed-save draft retention, unsaved-change guards and focus restoration.
20
+
21
+ ## Surface missing initialization prerequisites
22
+
23
+ As a feature introduces required business roles, direct managers or other real prerequisites, connect the standard [setup readiness](setup-readiness.md) hint to its authorized read paths in the same delivery, without asking the user to request a checklist. Reuse `RequiredRoleSetup` for explicitly declared business roles; use `SetupReadiness` and `useSetupReadiness` with a real business-owned aggregate for manager relationships. Show only applicable missing or indeterminate items and contextual configuration links; refresh after save and return, distinguish failed/denied reads from missing state, and retain server-side execution validation. Do not add startup scans, guessed relationships, automatic grants or a second Foundation inventory.
24
+
19
25
  ## Capability checklist
20
26
 
21
27
  | Actual business use | Administration to deliver automatically |
@@ -97,3 +103,11 @@ On template upgrades reconcile the editor, list/form/model, route contribution,
97
103
  ## Role assignment visibility
98
104
 
99
105
  Every application-owned role assignment created during building must be inspectable and adjustable in administration. Prefer explicit per-user assignments through the prepared User management page. Global defaults require an explicit user requirement and a protected control to inspect/change/remove the default, plus inherited-role source visibility in user details. Do not seed an invisible all-authenticated business role or present only direct roles as effective access. See [assignment safety](authorization.md#visible-and-manageable-assignments).
106
+
107
+ ## Contextual settings navigation
108
+
109
+ Reuse the prepared Users page for role membership rather than creating another member editor. Link with both `roleScope` and `role` (for example `/settings/users?roleScope=app&role=equipment-manager`) and an encoded `returnTo` containing the current application-relative workflow URL, including its filters. The page applies the paired server filters and preserves context across search, details, edits and clearing filters. A single role key without its scope is invalid. Configuration is an explicit member assignment, never an automatic grant based on a URL filter. Display labels from `users/options`, translated through their declared namespace, while retaining unknown keys and unchanged assignment values.
110
+
111
+ The prepared lists keep paging and sorting in URL state through `#hooks/use-table-url-state`. Preserve query strings in child links, close destinations and contextual configuration links. Correct pages beyond the last loaded page after a successful write/refetch; never clamp using stale rows while a query is loading or failed. Return destinations are application-relative and validated with `client/lib/return-to.ts`; never navigate to an arbitrary external URL. On success update the displayed record from the response and refresh the owning list; on failure/conflict retain the draft and require explicit confirmation before discarding it. Verify filtered list → detail/edit → failed save → successful save → close/return and browser history, not merely a successful toast.
112
+
113
+ `WorkflowDefinitionList.onSort` is optional: omit it when the adapter cannot actually order results instead of passing a no-op. Omit `name` when there is no useful secondary identifier; a linked title should not be accompanied by the same display name again. Registry components and template copies evolve together, and template upgrades merge these integrations without replacing application-specific routes, grants or edited policy.