@nocobase/app-skills 0.1.0-beta.36 → 0.1.0-beta.37

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.
Files changed (21) hide show
  1. package/package.json +2 -2
  2. package/skills/nocobase-app-development/SKILL.md +9 -1
  3. package/skills/nocobase-app-development/references/business-administration.md +86 -0
  4. package/skills/nocobase-app-development/references/database-connections.md +1 -1
  5. package/skills/nocobase-app-development/references/frontend/references/api.md +5 -0
  6. package/skills/nocobase-app-development/references/frontend/references/example/list-page.md +1 -1
  7. package/skills/nocobase-app-development/references/frontend/references/example/server-table.md +25 -107
  8. package/skills/nocobase-app-development/references/frontend/references/example.md +2 -2
  9. package/skills/nocobase-app-development/references/frontend/references/overlay.md +6 -5
  10. package/skills/nocobase-app-development/references/frontend/references/table.md +30 -25
  11. package/skills/nocobase-app-development/references/frontend/references/ui-library.md +5 -5
  12. package/skills/nocobase-app-development/references/frontend/ui-guidelines.md +2 -2
  13. package/skills/nocobase-app-development/references/lifecycle-parameters.md +5 -5
  14. package/skills/nocobase-app-development/references/lifecycle.md +8 -6
  15. package/skills/nocobase-app-development/references/server-routes.md +11 -1
  16. package/skills/nocobase-app-development/references/services-and-jobs.md +10 -0
  17. package/skills/nocobase-app-development/references/system-settings.md +83 -0
  18. package/skills/nocobase-app-development/references/template-variants.md +1 -1
  19. package/skills/nocobase-app-development/references/testing.md +16 -0
  20. package/skills/nocobase-app-upgrade/references/edge-cases.md +4 -0
  21. package/skills/nocobase-deployment/SKILL.md +2 -2
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.36",
3
+ "version": "0.1.0-beta.37",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -18,7 +18,7 @@
18
18
  "devDependencies": {
19
19
  "@playwright/test": "^1.62.1",
20
20
  "prettier": "^3.9.6",
21
- "@nocobase/dev-config": "0.1.0-beta.22"
21
+ "@nocobase/dev-config": "0.1.0-beta.23"
22
22
  },
23
23
  "peerDependencies": {
24
24
  "@playwright/test": "^1.62.1",
@@ -69,8 +69,14 @@ curl -H "x-api-key: <key>" http://127.0.0.1:13000/main/api/swagger
69
69
 
70
70
  Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is at `<APP_BASE_PATH>/api/swagger/docs`. Reading either needs a signed-in session or an API key, which a signed-in user creates with `POST <APP_BASE_PATH>/api/apiKeys`; without one the routes answer `401`, and an application with no access check registered, such as one without the authentication plugin, answers `404`. Ask the user for a key rather than creating one yourself. [HTTP API design](references/http-api.md#api-documentation) explains how to read the document and how a new route declares itself in it.
71
71
 
72
+ ## Include administration by default
73
+
74
+ 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 bound click-to-edit entries; 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.
75
+
72
76
  ## Frontend work
73
77
 
78
+ For business lists, reuse the template-provided `DataTable` and companions from `#components/data-table`, backed by the supported TanStack Table v8 dependency. Use its controlled manual mode for server paging/sorting. Do not replace it with an agent-written table engine when a dependency version is incompatible; inspect and repair the dependency first. See [tables](references/frontend/references/table.md).
79
+
74
80
  Before writing or changing anything under `client/` — pages, components, styles, copy — read [the frontend workflow](references/frontend/ui-workflow.md). It decides whether the change takes the full workflow (a design file reviewed once, then an independent acceptance review), a theme change (tokens and presets, verified with the theme tests and a browser check) or a quick change (edit directly, then the static checks, the related tests and one look at the changed element in the browser), and which parts of [the UI guidelines](references/frontend/ui-guidelines.md) and [the frontend handbook](references/frontend/frontend-dev.md) to read at each step.
75
81
 
76
82
  The handbook's "Look up by task" table routes each frontend task to the sections that cover it, and [the worked example](references/frontend/references/example.md) holds the complete files of the projects feature its rules are illustrated with. Components are shadcn/ui primitives, added with the CLI when a page first needs one: the shadcn/ui skill in `references/frontend/shadcn/` covers their API and composition rules, and [its guide in this handbook](references/frontend/references/shadcn.md) says what to read there and where this application departs from it.
@@ -84,7 +90,7 @@ Read the page for the task in front of you. Do not read all of them.
84
90
  | Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests | [frontend workflow](references/frontend/ui-workflow.md), which routes to the [frontend handbook](references/frontend/frontend-dev.md), the theme reference or the worked example |
85
91
  | Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
86
92
  | Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document | [HTTP API design](references/http-api.md) |
87
- | A list, dashboard or chart endpoint, or keeping one live: read with a fixed number of queries, refresh only what changed | [server routes](references/server-routes.md#lists-and-statistics-a-fixed-number-of-queries) and [client API requests](references/frontend/references/api.md#keeping-lists-and-charts-live) |
93
+ | A list, chart or polled endpoint, or keeping one live: read it with a fixed number of queries, refresh only what changed | [server routes](references/server-routes.md#lists-and-statistics-a-fixed-number-of-queries) and [client API requests](references/frontend/references/api.md#keeping-lists-and-charts-live) |
88
94
  | Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
89
95
  | Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
90
96
  | Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
@@ -165,6 +171,8 @@ When customizing template or registry UI, prefer existing props and composition,
165
171
 
166
172
  Treat disabling a feature as a reversible availability change by default: preserve its page and component source, conditionally exclude or guard its route, and hide its links and actions. A hidden navigation item alone does not disable direct URL access. Enforce the same feature policy on the server so direct API calls cannot execute the disabled operation. Do not delete feature code merely to remove it from the current UI; explicit permanent removal can justify deletion. See [pages and routes](references/frontend/references/page.md).
167
173
 
174
+ When workflows or approvals are used, deliver a standard process-management table first, even for a single process. A row opens that process's definition/design, node configuration and scoped execution history. Use the standard vertically arranged, automatically sized lifecycle diagram by default, with readable node summaries and configuration buttons; do not wait for an explicit request for these system settings. Reconcile later processes into the same directory and validate their identifiers and authorization on the server; a bare Home-only create-app still gets no unused settings. See [system settings delivery](references/system-settings.md).
175
+
168
176
  ## Non-negotiables
169
177
 
170
178
  These cause real damage and appear in every reference:
@@ -0,0 +1,86 @@
1
+ # Application-owned business administration
2
+
3
+ Use these recipes with [system settings delivery](system-settings.md) whenever a business feature implies administrator-maintained policy, reference data or operational visibility. They are implementation contracts for the building Agent, not claims that a generic dictionary, numbering or audit plugin is installed. Inspect the actual application and plugin Skills first, reuse existing services, and implement missing application-owned routes, migrations, permissions and pages as part of the feature. A bare Home-only application still registers none of these pages.
4
+
5
+ ## Delivery pattern
6
+
7
+ 1. Identify the administrator's actual decision and the business operation that consumes it. Define the scope, initial value and effective timing from the requirement or authoritative application state. Do not invent people, organization membership, regulatory policy or external credentials.
8
+ 2. Reuse the owning plugin's public API. For application-owned persistence, follow [database and data](database-and-data.md), [migrations](migrations.md) and [HTTP APIs](http-api.md). Do not assume platform endpoints exist because a package or a similar example is installed.
9
+ 3. Declare typed schemas, authorized read/write operations and stable keys. Validate and enforce scope on the server before looking up sensitive entities. Use an atomic revision precondition for concurrently edited settings, retaining drafts on conflicts.
10
+ 4. Connect the actual business execution to the persisted configuration. Add the existing Settings entry or contextual editor only after the backend contract works. Reuse standard DataTable for management lists and the standard parameter editor contract for bound lifecycle parameters.
11
+ 5. Reconcile existing state rather than re-seeding it. Create only missing defaults, routes and bindings, preserve edited values and unrelated grants, and verify a second reconciliation changes nothing. A schema evolution needs an explicit compatibility policy and migration where required.
12
+ 6. Verify a valid administrator change, execution with that change, denied direct requests, invalid input, concurrent edits and historical behavior. Report observed results and any unsupported capability; do not replace missing functionality with an editable-looking placeholder.
13
+
14
+ ## Business parameters
15
+
16
+ Extract administrator-owned values from actual business rules even without a configurability request: amounts, quantities, validity windows, warnings, supported switches or shared defaults. Keep authorization guards, workflow structure, technical constants and secrets source-owned. Infer administrator ownership from the business purpose and expected maintenance rather than requiring explicit "configurable" wording. Fixed technical/application invariants remain source-owned.
17
+
18
+ For a lifecycle, use [configurable lifecycle parameters](lifecycle-parameters.md), including explicit groups/bindings, complete-group saves, server validation, snapshot/live modes and usage history. For policy outside a lifecycle, inspect the application's existing service; otherwise implement an application-owned settings record with a stable key, typed payload, scope and revision. Use documented Repository/transaction contracts, reject undeclared fields, and compare the revision atomically when saving. The update response returns the effective saved values and revision; a stale write reports a conflict without overwriting either editor's work. This recipe does not add a generic platform configuration API.
19
+
20
+ Choose defaults from the requested policy or existing authoritative configuration and preserve them when the page is first enabled. Show units, bounds, dependent constraints and effective timing. Resolve the saved values in the real server-side calculation, route or task construction; shared caches must be invalidated consistently. A form over an unchanged hard-coded condition is incomplete. Decide whether documents retain the policy used when created/submitted or use current policy later; financial amounts and historical facts must not be silently recalculated.
21
+
22
+ For currency, units, reporting timezone and working calendars, define the affected calculation/report and storage convention before exposing edits. UI language, formatting timezone, business cutoff timezone and stored timestamps are different concerns. A display preference does not move historical timestamps or reschedule existing jobs. Startup configuration and browser-local preferences keep their documented ownership and precedence.
23
+
24
+ ## Business dictionaries
25
+
26
+ Use a dictionary when the business needs to maintain options such as expense categories, lead sources, priorities or reason codes. Fixed technical states and permission action identifiers stay in code. Customers, suppliers, products and other substantive business entities keep their own business modules.
27
+
28
+ Reuse an existing reference-data service or create application-owned dictionary/item persistence. Give each dictionary and item a stable identifier and unique key within the application's actual scope, plus a display label, sort order and enabled flag. Add translated labels or extra metadata only when the feature needs them. Bind forms, filters, imports and server validation to these authoritative entries; changing the Settings page alone must not leave a second hard-coded option list in use.
29
+
30
+ An ordinary create/edit picker offers enabled items. Existing records still resolve disabled referenced items for display, and editing an unrelated field must preserve their valid existing references. Disable an in-use item instead of cascading its deletion into business records; reject removal or key reuse that would corrupt references. Define whether historical documents use their captured label or the current label and preserve that convention on renames. Seed missing initial items by stable key without overwriting administrator changes on restart or later development.
31
+
32
+ Verify that a new item becomes available in the real business form, a disabled item cannot be newly assigned through a direct API request, existing references remain readable, and repeated provisioning does not duplicate or reset items. Verify scope boundaries and sorting, not just the appearance of a dictionary page.
33
+
34
+ ## Business document numbering
35
+
36
+ Provide this when users need a meaningful purchase-order, contract, invoice or request number. Internal primary keys remain generated by the application's normal ID service and are not editable numbering rules. Reuse an installed numbering service if present; otherwise implement the application-owned allocator with the database's documented atomic transaction/unique-constraint facilities.
37
+
38
+ Declare supported prefix, date segment, timezone, sequence partition and width fields with validation. Treat the format as constrained data rather than executable templates or arbitrary code. Show a non-consuming example; opening or previewing settings must not advance a counter. A rule change affects future allocation and never rewrites issued numbers or blindly resets a used counter.
39
+
40
+ Allocate in the authoritative server operation, using an atomic counter/reservation and a unique constraint in the correct business scope. A read-then-increment in application memory or a browser-generated number is insufficient. All create paths, imports, bulk actions and background jobs use the same allocator. Replay of the same successful logical request returns the same record/number; retry a transient allocation conflict without creating a second business operation. Define gaps and failed-transaction behavior explicitly; uniqueness does not imply gap-free numbering.
41
+
42
+ Test concurrent allocation, a replayed request, a failed transaction, a period boundary, a format change that could collide with existing numbers, and the absence of counter changes during preview. Preserve issued numbers and existing uniqueness guarantees when migrating a rule.
43
+
44
+ ## Important operation records
45
+
46
+ When implementing account/role administration, configurable business rules or other important administrator actions, reuse an installed audit/event service. If none exists and these actions need a history, implement application-owned server capture and storage with the feature rather than generating a log page with invented data. Diagnostic console logs and a row's current revision do not constitute a searchable change history.
47
+
48
+ Capture the authenticated actor, server timestamp, action, target identifier, scope, result and an allowlisted change summary at the authoritative service boundary. Cover alternate routes, bulk actions, jobs and retries where those operations exist. Successful database mutations and their audit fact must commit together, or use the application's transactional outbox with replay-safe delivery. Never report success for a rolled-back change. Denied attempts, reads, login failures and external outcomes use the appropriate independent event path when supported; they do not fabricate a committed database mutation.
49
+
50
+ Use a schema allowlist for before/after summaries; exclude credentials, tokens, secret settings, uploaded contents and unnecessary personal/business payloads. Display explicit unknown/unrecorded history for operations predating capture. Authorization must filter event rows and linked records on the server. Users allowed to view history do not gain permission to rewrite it. Retention and deletion follow the existing server/operations policy, with supported controls only.
51
+
52
+ Verify one actual change and its actor/result, a failed mutation without a false success entry, a replay without duplicate audit facts, protected fields absent from stored payloads, and an unauthorized history request. State any historical coverage or retention limitation accurately.
53
+
54
+ ## Extend the other capability surfaces
55
+
56
+ | Capability | Implementation boundary and observable result |
57
+ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | Organization and approval relationships | Reuse the actual organization source or explicitly enabled authentication extension with its migration. Maintain the real manager/member/position relationships used by approvals and data scope. Filter inactive/ineligible users on the server; changes follow the task/snapshot contract rather than silently replacing existing assignees. |
59
+ | Authentication and account security | Read the authentication and Users Skills. Enabled SSO, registration, MFA or passkeys need their supported configuration, migrations and UI. Offer actual account/session controls. Show login history only when captured; source-owned login policy and secrets do not become runtime-editable merely because there is a form. |
60
+ | Notifications and mail | Reuse the notification/mail Skills for channels, ownership, message/recipient rules and real delivery states. Configurable templates must be the ones the sender actually resolves. Keep credential updates on the supported server path, masked in reads. A manual resend uses the service's documented idempotency and unknown-submission semantics. |
61
+ | Files and storage | Reuse File Repository and the installed preview/attachment UI. Apply actual type/size policy on upload and authorized content reads. Provide relevant metadata/status and supported policy controls, while disk credentials and deployment-owned configuration remain with operations. |
62
+ | Scheduled work | Reuse the Scheduler Skill, with real targets, execution history, timezone and authorized enable/disable. Current Scheduler Cron definitions are code-owned; do not fabricate Cron editing or cancellation/retry APIs. Distinguish schedule availability from an already running execution. |
63
+ | Integrations, Webhooks and API access | Expose the connections and supported status/delivery/sync records actually used. Reuse the API Keys Skill; default endpoints own the current caller's keys and inherit that owner's session permissions. Per-key scopes require the documented alternative configuration and server enforcement. No default key, arbitrary secret readback or unimplemented Test connection button. |
64
+ | Printing and business templates | Read the template-print Skill: the package provides guidance, not a rendering service or an installed template-management API. Reuse fixed App assets when appropriate; implement authorized managed uploads/versioning only when business users need to maintain templates. The actual renderer consumes the selected version, and preview/download respect business data scope. |
65
+ | Import/export and bulk processing | Use authoritative dictionaries, field validation, business authorization and the shared numbering path. Record real processing results, rejected rows and failure details. Long work uses an installed job service when applicable, with only its supported progress/retry controls. Replays do not duplicate imported records or external effects. |
66
+ | App-owned AI/model calls and knowledge | Inspect the installed Agents/model-service and knowledge contracts. Mount real catalogs, enabled configuration, allowed prompt/content maintenance and available run diagnostics only when the application uses them. Knowledge may be versioned documents rather than a vector database. Do not invent model discovery, agent creation, token-cost statistics or editable credentials unsupported by the actual service. |
67
+
68
+ Read only the installed plugin Skills relevant to the capability. The application owns composition; a dependency alone creates neither a management page nor a runtime API.
69
+
70
+ ## Acceptance scenarios
71
+
72
+ Use a disposable application against one consistent package snapshot. Keep the capability request separate from administration hints so automatic delivery can actually be assessed. Record these as manual/unverified until an Agent build and runtime check have been performed; formatting or component tests do not prove Agent discovery.
73
+
74
+ | Request without asking for a settings page | Expected automatic delivery and verification |
75
+ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
76
+ | Create a basic Default App | Home only; no settings route/menu, business seed or empty capability cards. |
77
+ | Build a purchase-request register with employee/admin access, filtering and 65 records | Core Users/Roles, scoped server enforcement and standard DataTable with 20/20/20/5 paging. No unused workflow administration. |
78
+ | Classify requests by purchase category and report totals by category | Dictionary administration and real picker/API integration. Add/disable a category; existing references survive and disabled items cannot be newly assigned. |
79
+ | Give purchase requests human-readable numbers with a prefix and date | Numbering administration/preview and a shared atomic allocator. Concurrent requests have unique numbers; a replay returns the same record and preview consumes none. |
80
+ | Add manager approval and finance review above a stated amount | Definitions, standard diagram, threshold/reviewer configuration and authorized executions. Change a rule and verify a new eligible submission; preserve prior snapshots/tasks. |
81
+ | Warn when an item's stock falls below 10, without an approval flow | Real typed business settings consumed by the server's warning calculation; no artificial lifecycle dependency or unused workflow page. |
82
+ | Change a role or a business rule | An authorized real operation record with actor/time/result and safe change summary; failed/replayed writes follow the defined event semantics. |
83
+ | Add notifications, scheduled reminders, attachments or an external integration in later rounds | Only the used capability's supported administration appears, with actual status/results and correct ownership. Existing settings, values and permissions remain intact. |
84
+ | Repeat a feature iteration and restart | No duplicate routes, dictionary items, rules, counters, role grants or configuration bindings; administrator edits and historical data remain intact. |
85
+
86
+ For chosen interfaces also verify loading/empty/error states, failed saves, conflict drafts, an ordinary user's denied direct requests, Chinese/English, light/dark and narrow layouts. Keep the delivery report factual: identify what was generated, what ran, and what remains unverified.
@@ -211,4 +211,4 @@ Application server builds retain declaration emission with `isolatedDeclarations
211
211
 
212
212
  Application templates declare `@nocobase/db-sqlite`, the driver for the dialect their `server/config/database.ts` defaults to, and `create-app` adds no other. Any further driver an application's configuration needs — for its main connection or an additional one — has to be installed into its `dependencies` before building, because a deployment installs only what the application declares.
213
213
 
214
- KingbaseES, Dameng and OceanBase drivers are maintained in `nocobase/nocobase3-pro` and distributed through the Pro registry. Install the selected package in the application’s production dependencies, then configure its dialect and connection settings. Automatic loading and `config init --dialect` remain supported; explicit registration in `database.drivers` is optional and takes precedence.
214
+ KingbaseES, Dameng and OceanBase drivers are NocoBase Pro commercial packages requiring the appropriate commercial license and authenticated access to the private package registry. Install the selected package in the application’s production dependencies, then configure its dialect and connection settings. Automatic loading and `config init --dialect` remain supported; explicit registration in `database.drivers` is optional and takes precedence.
@@ -307,6 +307,11 @@ When realtime events refresh what a page shows:
307
307
  - Recompute a chart's figures at most every few seconds while it is visible, and not at all while the page is hidden; or update only the figure the event affects.
308
308
  - Read nothing for a page that is not shown; read it when it is shown again.
309
309
  - A component that needs one small fact reads the small endpoint that answers it, not the list that happens to contain it.
310
+ - Keep realtime subscriptions in one place, such as the page or a hook it owns, rather than one per row or card, and subscribe only to the topics the page shows.
311
+ - When a refresh is triggered while a request for the same data is still in flight, usually let it finish and read once more afterwards rather than aborting it and sending it again; repeated aborts under a stream of events can mean no request ever completes. Aborting is still right when the parameters change or the component unmounts, as above.
312
+ - Skip fetching while the page is hidden (`document.visibilityState`), and refresh once when it becomes visible again.
313
+ - Keep request keys stable: build them from the parameters that decide the data, not from values that change on every render or tick, such as the current time, or each change starts a new request.
314
+ - Be careful with data loaded by components mounted on every page, such as navigation or a header badge: they run on every page and in every open tab, so they usually read a small fact rather than a list.
310
315
 
311
316
  The server side of these reads is in [server routes](../../server-routes.md#lists-and-statistics-a-fixed-number-of-queries).
312
317
 
@@ -4,7 +4,7 @@ Part of the [projects worked example](../example.md).
4
4
 
5
5
  **Depends on**: [delete dialog](delete-dialog.md), [status badge](../i18n.md#dynamic-keys), [session alert](session-expired-alert.md), [types](types.md), [search hook](url-search.md), [copy](copy.md); the `projects` route in [section 1 of `page.md`](../page.md#1-declare-the-route).
6
6
 
7
- **Add first**: `yes n | pnpm exec shadcn add alert empty input-group select skeleton table`, then format the files it creates ([how](../shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)), and build `DataTable` in `client/components/data-table/` with `@tanstack/react-table` in `devDependencies` ([section 1 of `table.md`](../table.md#1-choosing-a-table-component)).
7
+ **Add first**: `yes n | pnpm exec shadcn add alert empty input-group select skeleton table`, then format the files it creates ([how](../shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)), and reuse the template's shipped `DataTable` in `client/components/data-table/` with its supported `@tanstack/react-table` v8 dependency ([section 1 of `table.md`](../table.md#1-choosing-a-table-component)).
8
8
 
9
9
  **Links to**: the [create dialog](create-dialog.md), the [detail drawer](detail-drawer.md) and the [edit dialog](edit-dialog.md), which a row's menu opens alone, are its child routes. Without a detail view, render the name as plain text: a link to a route that does not exist lands on the home page.
10
10
 
@@ -8,7 +8,7 @@ Part of the [projects worked example](../example.md).
8
8
 
9
9
  **Links to**: the same child routes as the list page.
10
10
 
11
- Rules: [section 1 of `table.md`](../table.md#1-choosing-a-table-component). Use it instead of `DataTable` when the endpoint paginates; the list page keeps the page in the URL and passes it down.
11
+ Rules: [section 1 of `table.md`](../table.md#1-choosing-a-table-component). This adapter uses the standard `DataTable` in manual mode when the endpoint paginates; the list page keeps the page in the URL and passes it down.
12
12
 
13
13
  The endpoint contract this assumes is the one in [types](types.md): `GET /api/projects` takes `page` (from 1), `pageSize` (at most 100) and `orderBy` besides `q` and `status`, and returns `{ data: Project[], meta: { page, pageSize, total } }` (`ProjectList`), where `total` counts the matching records on all pages. `orderBy` names a column the endpoint sorts by, `name` (in the order of the request's language) or `updatedAt`, followed by ` desc` for descending; the page always sends it, `updatedAt desc` by default (guideline T1.8).
14
14
 
@@ -225,49 +225,27 @@ The component it renders:
225
225
 
226
226
  ```tsx
227
227
  // client/pages/projects/projects-server-table.tsx
228
- import {
229
- type ColumnDef,
230
- flexRender,
231
- getCoreRowModel,
232
- type PaginationState,
233
- type SortingState,
234
- useReactTable,
228
+ import type {
229
+ ColumnDef,
230
+ PaginationState,
231
+ SortingState,
235
232
  } from '@tanstack/react-table';
236
233
  import type { ReactElement, ReactNode } from 'react';
237
-
238
- import { DataTablePagination } from '#components/data-table/pagination';
239
- import {
240
- Table,
241
- TableBody,
242
- TableCell,
243
- TableHead,
244
- TableHeader,
245
- TableRow,
246
- } from '#components/ui/table';
247
-
234
+ import { DataTable } from '#components/data-table';
248
235
  import type { Project } from './types.js';
249
236
 
250
237
  export interface ProjectsServerTableProps {
251
238
  readonly columns: ColumnDef<Project>[];
252
- /** The rows of the current page, as the endpoint returned them. */
253
239
  readonly rows: Project[];
254
- /** The number of matching records on all pages, from the endpoint. */
255
240
  readonly total: number;
256
- /** The page read from the URL; pageIndex starts at 0. */
257
241
  readonly pagination: PaginationState;
258
- /** Writes the new page to the URL; the list request follows the URL. */
259
242
  readonly onPaginationChange: (pagination: PaginationState) => void;
260
- /** The sort read from the URL, which the endpoint applied. */
261
243
  readonly sorting: SortingState;
262
- /** Writes the new sort to the URL; the list request follows the URL. */
263
244
  readonly onSortingChange: (sorting: SortingState) => void;
264
- /** Shown when the page has no rows, as DataTable's emptyMessage. */
265
245
  readonly emptyMessage: ReactNode;
266
- /** The rows-per-page choices; the list page accepts only these from the URL. */
267
246
  readonly pageSizeOptions: readonly number[];
268
247
  }
269
248
 
270
- /** The markup of DataTable, paginated and sorted by the server instead of the browser. */
271
249
  export function ProjectsServerTable({
272
250
  columns,
273
251
  rows,
@@ -279,86 +257,26 @@ export function ProjectsServerTable({
279
257
  emptyMessage,
280
258
  pageSizeOptions,
281
259
  }: ProjectsServerTableProps): ReactElement {
282
- // TanStack Table returns a mutable instance the React Compiler cannot memoize, as in `data-table/index.tsx`.
283
- // eslint-disable-next-line react-hooks/incompatible-library
284
- const table = useReactTable({
285
- data: rows,
286
- columns,
287
- getRowId: (row) => row.id,
288
- getCoreRowModel: getCoreRowModel(),
289
- // The server already paginated and sorted: no pagination or sorted row model, and the page count comes from
290
- // rowCount. Sorting one page in the browser would mislead, so the header only shows and changes the URL's sort.
291
- manualPagination: true,
292
- manualSorting: true,
293
- rowCount: total,
294
- state: { pagination, sorting },
295
- onPaginationChange: (updater) => {
296
- onPaginationChange(
297
- typeof updater === 'function' ? updater(pagination) : updater,
298
- );
299
- },
300
- onSortingChange: (updater) => {
301
- onSortingChange(
302
- typeof updater === 'function' ? updater(sorting) : updater,
303
- );
304
- },
305
- });
306
- const pageRows = table.getRowModel().rows;
307
-
308
260
  return (
309
- <div className='flex flex-col gap-4'>
310
- <div className='overflow-hidden rounded-lg border'>
311
- <Table>
312
- <TableHeader>
313
- {table.getHeaderGroups().map((headerGroup) => (
314
- <TableRow key={headerGroup.id}>
315
- {headerGroup.headers.map((header) => (
316
- <TableHead key={header.id} colSpan={header.colSpan}>
317
- {header.isPlaceholder
318
- ? null
319
- : flexRender(
320
- header.column.columnDef.header,
321
- header.getContext(),
322
- )}
323
- </TableHead>
324
- ))}
325
- </TableRow>
326
- ))}
327
- </TableHeader>
328
- <TableBody>
329
- {pageRows.length > 0 ? (
330
- pageRows.map((row) => (
331
- <TableRow key={row.id}>
332
- {row.getVisibleCells().map((cell) => (
333
- <TableCell key={cell.id}>
334
- {flexRender(
335
- cell.column.columnDef.cell,
336
- cell.getContext(),
337
- )}
338
- </TableCell>
339
- ))}
340
- </TableRow>
341
- ))
342
- ) : (
343
- <TableRow>
344
- <TableCell
345
- colSpan={columns.length}
346
- className='h-24 text-center text-muted-foreground'
347
- >
348
- {emptyMessage}
349
- </TableCell>
350
- </TableRow>
351
- )}
352
- </TableBody>
353
- </Table>
354
- </div>
355
- {/* Reads the page index and page count from the table instance. */}
356
- <DataTablePagination
357
- table={table}
358
- pageSizeOptions={pageSizeOptions}
359
- showSelectedCount={false}
360
- />
361
- </div>
261
+ <DataTable
262
+ columns={columns}
263
+ data={rows}
264
+ getRowId={(row) => String(row.id)}
265
+ manualPagination
266
+ rowCount={total}
267
+ paginationState={pagination}
268
+ onPaginationChange={(next) =>
269
+ onPaginationChange(typeof next === 'function' ? next(pagination) : next)
270
+ }
271
+ manualSorting
272
+ sortingState={sorting}
273
+ onSortingChange={(next) =>
274
+ onSortingChange(typeof next === 'function' ? next(sorting) : next)
275
+ }
276
+ emptyMessage={emptyMessage}
277
+ pageSizeOptions={pageSizeOptions}
278
+ showSelectedCount={false}
279
+ />
362
280
  );
363
281
  }
364
282
  ```
@@ -18,10 +18,10 @@ Read the document for your task, and every document its **Depends on** line name
18
18
 
19
19
  The template ships neither `client/components/session-expired-alert.tsx` nor `client/hooks/use-url-search.ts`. They are shared infrastructure rather than feature code: the first feature that needs one copies it unchanged from its document here, and later features import it.
20
20
 
21
- The template ships only the shadcn/ui primitives its shell uses, and no `DataTable`. A document whose file imports another primitive or `DataTable` says so on its **Add first** line; run that command before your code imports one, then format the files it creates, as [section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest) describes. The whole feature needs:
21
+ The template ships the standard `DataTable` and its companions plus the primitives its shell and compositions use. A document whose file imports another primitive or `DataTable` says so on its **Add first** line; run that command before your code imports one, then format the files it creates, as [section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest) describes. The whole feature needs:
22
22
 
23
23
  ```bash
24
24
  yes n | pnpm exec shadcn add alert alert-dialog badge card chart checkbox combobox empty field input-group radio-group select skeleton switch table textarea
25
25
  ```
26
26
 
27
- `chart` installs `recharts`; move it to `devDependencies` ([section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)). `DataTable` is built in `client/components/data-table/` before the first list, as [section 1 of `table.md`](table.md#1-choosing-a-table-component) describes, with `@tanstack/react-table` in `devDependencies`.
27
+ `chart` installs `recharts`; move it to `devDependencies` ([section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)). `DataTable` is already shipped in `client/components/data-table/` and should be reused, as [section 1 of `table.md`](table.md#1-choosing-a-table-component) describes, with `@tanstack/react-table` in `devDependencies`.
@@ -104,7 +104,7 @@ Both take the same props:
104
104
  | `title` | `ReactNode`, required | Title at the top, which is also the overlay's accessible name |
105
105
  | `description` | `ReactNode` | Description under the title |
106
106
  | `children` | `ReactNode` | Content area; scrolls internally when its content exceeds the height |
107
- | `footer` | `ReactNode` | Fixed bottom area with the layout `flex flex-wrap justify-end gap-2`: the buttons sit together on the right and wrap on narrow screens |
107
+ | `footer` | `ReactNode` | Fixed bottom area rendered in `DialogFooter`: the buttons sit together on the right, and on narrow screens they stack with the last one on top |
108
108
  | `closeTo` | `To` | Where to go after closing. Defaults to the parent route `{ pathname: '..', search: location.search, hash: '' }`, resolved by route hierarchy, keeping the query parameters and dropping the hash |
109
109
  | `beforeClose` | `() => boolean \| Promise<boolean>` | Called before closing; returning `false` keeps the overlay open |
110
110
  | `className` | `string` | Added to the panel to adjust its width: dialogs default to `sm:max-w-2xl`, drawers to `sm:max-w-xl`; a create or edit dialog of 1–4 fields passes `sm:max-w-md` (guideline I1) |
@@ -112,7 +112,8 @@ Both take the same props:
112
112
  What the components already do:
113
113
 
114
114
  - **Size**: a dialog is centered, is the screen width minus 2rem wide on narrow screens, and has a maximum height of `100dvh - 2rem`; a drawer sits against the right edge at full height and takes the full width on narrow screens. The title area and the bottom button area are fixed and only the content area scrolls, so the bottom buttons stay reachable on narrow screens too (guideline A4); there is no need to add `max-h` or `overflow` to the panel.
115
- - **Content container**: the content area already has `p-4` padding. Do not nest a `PageContainer` inside it, and do not add outer padding of your own.
115
+ - **Content container**: the content area already has the dialog's padding. Do not nest a `PageContainer` inside it, and do not add outer padding of your own.
116
+ - **Look**: the title, description and footer are the dialog primitives (`DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter` from `#components/ui/dialog`) inside the same padding, spacing and close-button position as `DialogContent`, so a route overlay looks like any other dialog of the application, and a change to the dialog primitive or its theme rules reaches both. A drawer uses the same regions against the right edge.
116
117
  - **Ways to close**: a close button is built into the top-right corner (its accessible name comes from `routeOverlay.close`); Esc and clicking the backdrop close the overlay too. Each overlay layer has its own backdrop, and when layers stack only the topmost one closes.
117
118
  - **Closing is navigation**: closing first calls `beforeClose`, then navigates to `closeTo` with `replace`. Because it uses `replace`, pressing the browser's "Forward" after closing does not reopen the overlay.
118
119
  - **Focus**: on open, focus moves into the overlay; when the focused element inside the overlay disappears (for example, a button is replaced by a skeleton after clicking "Retry"), focus returns to the overlay panel; after closing, focus returns to the element that had focus before opening (usually the link that opened it; for a row menu's "Edit", the menu's trigger). When a nested overlay closes, focus returns to the element in the parent layer that opened it, or to the parent layer's panel if that element is gone; when `/projects/12/edit` is opened directly, both layers mount at once, and after the dialog closes, focus is on the drawer panel.
@@ -371,7 +372,7 @@ The details below describe `sheet.tsx` as the registry writes it today; the file
371
372
 
372
373
  ## 6. Plain dialogs: sizes and scrolling
373
374
 
374
- A `Dialog` from `#components/ui/dialog` defaults to `sm:max-w-sm` and grows with its content without limit. Give it the width guideline I1 assigns to what it holds, and when its content can outgrow the screen, cap its height with the one idiom `max-h-[calc(100dvh-2rem)]` and scroll only its body, so the header and the footer's buttons stay in view (guideline A4):
375
+ A `Dialog` from `#components/ui/dialog` defaults to `sm:max-w-lg` and grows with its content without limit. Give it the width guideline I1 assigns to what it holds, and when its content can outgrow the screen, cap its height with the one idiom `max-h-[calc(100dvh-2rem)]` and scroll only its body, so the header and the footer's buttons stay in view (guideline A4):
375
376
 
376
377
  ```tsx
377
378
  // A small form: 1–4 fields, the width alone.
@@ -380,12 +381,12 @@ A `Dialog` from `#components/ui/dialog` defaults to `sm:max-w-sm` and grows with
380
381
  // Content that can outgrow the screen: a fixed header and footer around a scrolling body.
381
382
  <DialogContent className='flex max-h-[calc(100dvh-2rem)] flex-col sm:max-w-2xl'>
382
383
  <DialogHeader>…</DialogHeader>
383
- <div className='-mx-4 min-h-0 flex-1 overflow-y-auto px-4'>…</div>
384
+ <div className='-mx-6 min-h-0 flex-1 overflow-y-auto px-6'>…</div>
384
385
  <DialogFooter>…</DialogFooter>
385
386
  </DialogContent>
386
387
  ```
387
388
 
388
- - `flex flex-col` replaces the content's grid, and `min-h-0 flex-1` lets the body shrink and scroll; `-mx-4 … px-4` runs its scrollbar along the dialog's edge. When the body is the form, put the classes on the `form` and keep the submit button in `DialogFooter` with `form='…'`.
389
+ - `flex flex-col` replaces the content's grid, and `min-h-0 flex-1` lets the body shrink and scroll; `-mx-6 … px-6` matches the content's `p-6` and runs its scrollbar along the dialog's edge. When the body is the form, put the classes on the `form` and keep the submit button in `DialogFooter` with `form='…'`.
389
390
  - Do not cap the height any other way (`90vh`, `85dvh`, `calc(100svh-2rem)`, `min(40rem,…)`), and do not put `overflow-y-auto` on `DialogContent` itself: the footer would scroll away with the content.
390
391
  - Large read-only content (a transcript, a diff, a file preview) uses the same structure at `sm:max-w-4xl`, usually with no footer.
391
392
  - `RouteDialog` and `RouteDrawer` are built this way already; pass them only a width.
@@ -6,7 +6,9 @@ This document uses `client/pages/projects/index.tsx` as its example; the complet
6
6
 
7
7
  ## 1. Choosing a table component
8
8
 
9
- Build every list with `DataTable` (`#components/data-table`, built on TanStack Table) and its companions in `client/components/data-table/`: `DataTableColumnHeader` (a sortable column header), `DataTablePagination` (the pagination bar) and `DataTableViewOptions` (the "Toggle columns" menu). They are the application's own: before the first list, build them in that directory from the `button`, `dropdown-menu`, `select` and `table` primitives and `@tanstack/react-table` (in `devDependencies`), following shadcn's [Data Table guide](https://ui.shadcn.com/docs/components/data-table) and giving `DataTable` the props of [section 2](#2-datatable-props). Do not write a list from scratch with `Table`. The one exception is server-side pagination below. A short list of records inside a card, such as a dashboard's, is a `DataTable` too, with plain headers and `pagination={false}` (guideline T5.3); in an ordinary `CardContent` it lines up with the card's title by itself ("Table in a card" in ["Common layouts" of `styling.md`](styling.md#common-layouts); [`example/project-dashboard.md`](example/project-dashboard.md)).
9
+ Use the standard `DataTable` and companions already shipped in `client/components/data-table/`, imported through `#components/data-table`: `DataTableColumnHeader`, `DataTablePagination` and `DataTableViewOptions`. Both templates declare `@tanstack/react-table` through the repository's v8 catalog range, and the lockfile resolves 8.21.3. Application ownership of these source files is intentional; replacing the TanStack engine with an agent-written table engine is not. Do not rebuild these components for every app. A short list inside a card uses the same component with `pagination={false}`. For older applications missing the standard files, copy the compatible template implementation and its primitives and dependencies before building list pages.
10
+
11
+ If an installed dependency does not expose `useReactTable` and `getCoreRowModel`, inspect the actual resolved package/version and repair the dependency to the supported v8 range (for example `pnpm add -D @tanstack/react-table@^8.21.3`). Do not install an unqualified latest major, invent substitute hooks, abandon TanStack, or merely document the deviation. A normal dependency installation and a compile test must verify the repaired exports. A historical `.agents/rules/components.md` note about missing exports records a migration issue, not an accepted substitute for the standard component. Inspect the affected application, restore the compatible dependency and TanStack implementation, and update that note only after its checks pass.
10
12
 
11
13
  | Scenario | What to use |
12
14
  | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
@@ -16,7 +18,7 @@ Build every list with `DataTable` (`#components/data-table`, built on TanStack T
16
18
  - Leave search and filtering to the backend: pass the filters as endpoint parameters; `DataTable` only displays, sorts and paginates.
17
19
  - The complete list page, [`example/list-page.md`](example/list-page.md), shows column definitions, the toolbar outside `DataTable`, a row actions menu and the four states working together.
18
20
 
19
- Server-side pagination, when the endpoint takes `page` and `pageSize` and returns the total. `DataTable` paginates in the browser only, so the page renders `ProjectsServerTable` instead: the same markup as `DataTable`, a TanStack table with `manualPagination` and `rowCount`, and `DataTablePagination` below it. [`example/server-table.md`](example/server-table.md) has both the component and the complete list page that uses it:
21
+ Server-side pagination uses the same standard `DataTable`: pass `manualPagination`, `rowCount`, controlled `paginationState` and `onPaginationChange`; add `manualSorting`, `sortingState` and `onSortingChange` when the endpoint sorts. The component does not paginate or sort the already paginated server response again. Keep page, page size, sort and filters in the URL. The thin `ProjectsServerTable` adapter in [`example/server-table.md`](example/server-table.md) translates page-specific props to the standard component; it does not rebuild table markup or a TanStack instance.
20
22
 
21
23
  - Keep `page` and `pageSize` in the URL beside `q` and `status`, written through the same `updateParams` ([section 5](#5-writing-search-and-filters-to-the-url)), and reset `page` when a filter changes. Include both in the request key and in `query`.
22
24
  - Pass the component the current page's rows, the returned total, `{ pageIndex: page - 1, pageSize }` read from the URL, and an `onPaginationChange` that writes the new values back to the URL; the request follows the URL.
@@ -25,32 +27,35 @@ Server-side pagination, when the endpoint takes `page` and `pageSize` and return
25
27
 
26
28
  ## 2. DataTable props
27
29
 
28
- | Prop | Description |
29
- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
- | `columns` | `ColumnDef<T>[]`, created with `useMemo` |
31
- | `data` | Row data, `T[]` |
32
- | `getRowId` | Returns a stable row id, for example `(row) => row.id` |
33
- | `emptyMessage` | What the table shows when there are no rows (default: "No results."); use it for the no-results message and "Clear filters" |
34
- | `pageSize`, `pageSizeOptions` | Rows per page, default 10; the selectable rows-per-page values default to `[10, 20, 30, 40, 50]` |
35
- | `pagination` | When set to `false`, all rows are shown and there is no pagination bar |
36
- | `toolbar` | `(table) => ReactNode`, rendered above the table inside `DataTable`, with access to the table instance. For browser-side filtering and `DataTableViewOptions` |
37
- | `onRowClick` | Makes the whole row clickable. Do not use it when the row contains links, buttons or menus, because the clicks conflict. It does not work from the keyboard, so the first column still needs a link |
38
- | `className` | Class name of the outer container |
39
- | `showSelectedCount` | Defaults to `true`; pass `false` on a table without row selection so the pagination bar does not show "0 of N row(s) selected" |
30
+ | Prop | Description |
31
+ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
32
+ | `columns` | `ColumnDef<T>[]`, created with `useMemo` |
33
+ | `data` | Row data, `T[]` |
34
+ | `getRowId` | Returns a stable row id, for example `(row) => row.id` |
35
+ | `emptyMessage` | What the table shows when there are no rows (default: "No results."); use it for the no-results message and "Clear filters" |
36
+ | `pageSize`, `pageSizeOptions` | Rows per page, default 10; the selectable rows-per-page values default to `[10, 20, 30, 40, 50]` |
37
+ | `pagination` | When set to `false`, all rows are shown and there is no pagination bar |
38
+ | `toolbar` | `(table) => ReactNode`, rendered above the table inside `DataTable`, with access to the table instance. For browser-side filtering and `DataTableViewOptions` |
39
+ | `onRowClick` | Makes the whole row clickable. Do not use it when the row contains links, buttons or menus, because the clicks conflict. It does not work from the keyboard, so the first column still needs a link |
40
+ | `className` | Class name of the outer container |
41
+ | `manualPagination`, `rowCount`, `paginationState`, `onPaginationChange` | Server paging: rows are the current server page, total controls page count, state and changes belong to the page |
42
+ | `manualSorting`, `sortingState`, `onSortingChange` | Server sorting: the endpoint applies the controlled sort, not the browser |
43
+ | `loading` | Marks the table busy and disables paging controls while preserving visible rows |
44
+ | `showSelectedCount` | Defaults to `true`; pass `false` on a table without row selection so the pagination bar does not show "0 of N row(s) selected" |
40
45
 
41
46
  ## 3. Known DataTable behavior
42
47
 
43
- The following holds for `client/components/data-table/` built from shadcn's [Data Table guide](https://ui.shadcn.com/docs/components/data-table) with the props of section 2. Know these points before you use it, and handle them as needed in the design and the implementation:
44
-
45
- | Behavior | Impact | What to do |
46
- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
47
- | The pagination bar shows "N of M row(s) selected" by default | A table without row selection would show "0 of N row(s) selected." | Pass `showSelectedCount={false}` on a table without selection. An application generated before `DataTable` had this prop adds it: `readonly showSelectedCount?: boolean` in `DataTableProps`, defaulted to `true` and passed to `<DataTablePagination>` |
48
- | `DataTableViewOptions` shows raw column ids and is hidden below `lg` | Without `getColumnLabel` the menu lists `column.id` (untranslated, guideline C1); its trigger is `hidden lg:flex`, so on phones and tablets a hidden column cannot be restored | Render it as `toolbar={(table) => <DataTableViewOptions table={table} getColumnLabel={(column) => t(…)} />}` with translated labels. When the page does not need column toggling, set `enableHiding: false` on the columns instead of offering the menu |
49
- | The header menu of a sortable column includes "Hide" | If the page has no "Toggle columns" entry, a hidden column cannot be brought back | Write `enableHiding: false` in the column definition, or put `DataTableViewOptions` in `toolbar` |
50
- | No initial sorting state | The default order can only be the order the endpoint returns, and no header shows a sort direction until the user sorts | Have the endpoint return the default order (guideline T1.8: most recently updated first). The server-paginated table keeps the sort in the URL, so its header shows the default direction; if a browser-sorted list must show it too, add an optional `initialSorting` prop to `DataTable` |
51
- | Returns to page 1 when the data changes | Search, filtering, refreshing and deleting all return to page 1 | Usually what you want. To stay on the current page, change `DataTable` (for example, add an `autoResetPageIndex` prop passed through to `useReactTable`) and handle the current page exceeding the page count after a delete |
52
- | Browser-side sorting compares character codes | Chinese is not sorted by pinyin | Offer no sorting on Chinese columns, or write a `sortingFn` in the column definition that compares with `Intl.Collator(locale)` (the example's name column does this) |
53
- | The built-in `toolbar` container does not wrap | With several controls in it, it overflows on narrow screens | Put the page's own search and filters outside `DataTable`, using `flex flex-wrap` (as the example does) |
48
+ The following holds for the standard `client/components/data-table/` implementation shipped in the templates. Know these points before you use it, and handle them as needed in the design and the implementation:
49
+
50
+ | Behavior | Impact | What to do |
51
+ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
52
+ | The pagination bar shows "N of M row(s) selected" by default | A table without row selection would show "0 of N row(s) selected." | Pass `showSelectedCount={false}` on a table without selection. An application generated before `DataTable` had this prop adds it: `readonly showSelectedCount?: boolean` in `DataTableProps`, defaulted to `true` and passed to `<DataTablePagination>` |
53
+ | `DataTableViewOptions` shows raw column ids | Without `getColumnLabel` the menu lists `column.id` (untranslated, guideline C1); the trigger remains available on narrow screens | Render it as `toolbar={(table) => <DataTableViewOptions table={table} getColumnLabel={(column) => t(…)} />}` with translated labels. When the page does not need column toggling, set `enableHiding: false` on the columns instead of offering the menu |
54
+ | The header menu of a sortable column includes "Hide" | If the page has no "Toggle columns" entry, a hidden column cannot be brought back | Write `enableHiding: false` in the column definition, or put `DataTableViewOptions` in `toolbar` |
55
+ | No initial sorting state | The default order can only be the order the endpoint returns, and no header shows a sort direction until the user sorts | Have the endpoint return the default order (guideline T1.8: most recently updated first). The server-paginated table keeps the sort in the URL, so its header shows the default direction; if a browser-sorted list must show it too, add an optional `initialSorting` prop to `DataTable` |
56
+ | Returns to page 1 when the data changes | Search, filtering, refreshing and deleting all return to page 1 | Usually what you want. To stay on the current page, change `DataTable` (for example, add an `autoResetPageIndex` prop passed through to `useReactTable`) and handle the current page exceeding the page count after a delete |
57
+ | Browser-side sorting compares character codes | Chinese is not sorted by pinyin | Offer no sorting on Chinese columns, or write a `sortingFn` in the column definition that compares with `Intl.Collator(locale)` (the example's name column does this) |
58
+ | The built-in `toolbar` container wraps | Keep controls usable at narrow widths | Put the page's own search and filters outside `DataTable`, using `flex flex-wrap` (as the example does) |
54
59
 
55
60
  ## 4. Changing shared components
56
61
 
@@ -136,14 +136,14 @@ The /device page where a signed-in person approves or denies the sign-in of a CL
136
136
 
137
137
  ### permission-editor
138
138
 
139
- A role's permissions as collapsible sections of switch rows under optional subheadings, each row reaching a level picked in a fixed right column. Use it for a role editor. Presentational: map the business actions and levels @nocobase/app-plugin-authorization registers to sections of rows.
139
+ A compact resource permission workspace with horizontal action checkboxes, adjacent data scopes and atomic visible selection.
140
140
 
141
141
  - Kind: component
142
142
  - Install: `yes n | pnpm exec shadcn add @nocobase/permission-editor`
143
- - Installs to: `client/components/permission-editor.tsx`
143
+ - Installs to: `client/components/permission-editor.tsx`, `client/components/permission-filter.tsx`
144
144
  - Plugin dependencies: none
145
145
  - Example: `@nocobase/permission-editor-demo` (`pnpm exec shadcn view @nocobase/permission-editor-demo`)
146
- - After installing: Map your permissions to sections of groups of rows; each row has an id, a label, an optional hint, whether it is enabled, and optionally the levels it can reach and the current one. onEnabledChange and onLevelChange report changes by row id. Every word comes through props, English by default.
146
+ - After installing: Map your permissions to sections of groups of rows; each row has an id, a label, an optional hint, whether it is enabled, and optionally the levels it can reach and the current one. onEnabledChange and onLevelChange report changes by row id. Every word comes through props, English by default. Resource groups render as compact rows with wrapping action checkboxes. Optional row.scopes bind independent scope selectors to their owning action. Pass onEnabledBatchChange to enable atomic group selection of visible toggleable permissions; omit it to keep single-action controls. Filtering never mutates the draft. Pass labels.selectVisible for the localized group checkbox name. Use group.accessOnly for a page with a single access action to show one title checkbox without redundant action text. Provide scope.configuration for parameterized scopes; PermissionFilter edits validated condition drafts and keeps role saving in the host form. Never save customFilter as a bare key: bind its native params.filter object.
147
147
 
148
148
  ## Data display
149
149
 
@@ -239,7 +239,7 @@ Read-only React Flow canvas with ELK orthogonal routing for directed graphs, inc
239
239
  - Installs to: `client/components/flow-diagram.tsx`, `client/components/flow-layout.ts`, `client/components/flow-diagram-css.d.ts`
240
240
  - Plugin dependencies: none
241
241
  - Example: `@nocobase/flow-diagram-demo` (`pnpm exec shadcn view @nocobase/flow-diagram-demo`)
242
- - After installing: Pass nodes and edges with unique ids, an ariaLabel and either a bounded canvas height or autoHeight. Use direction DOWN with autoHeight for detailed page diagrams; height follows the full layout including outer routes and labels. The default node is 200×64 canvas units; set width/height for richer renderNode content. direction is RIGHT or DOWN. onNodeClick/onEdgeClick open your details; onLayoutError reports invalid graph or layout failures. Translate flowDiagram.empty, loading, failed, nodeHelp and edgeHelp; see the components README. Includes React Flow CSS. Uses application primary/card/foreground/border tokens in light and dark themes. Ordinary edges are subdued, solid and labeled directly on the route. Set visited on nodes/edges for actual history and highlighted for the current node or available edges; current nodes have a stronger fill and ring. ELK optimizes port order to reduce crossings. Decorative nodes/edges are not focusable or selectable.
242
+ - After installing: Pass nodes and edges with unique ids, an ariaLabel and either a bounded canvas height or autoHeight. Use direction DOWN with autoHeight for detailed page diagrams; height follows the full layout including outer routes and labels. The default node is 232×104 canvas units; set width/height for richer renderNode content. direction is RIGHT or DOWN. nodeDescription and nodeActions add supporting summaries and configuration controls. For bounded canvases, initialMinZoom=0.8 preserves initial readability and showMiniMap provides overview navigation; Fit still shows the whole graph. Translate flowDiagram.overview when using the minimap. onNodeClick/onEdgeClick open your details; onLayoutError reports invalid graph or layout failures. Translate flowDiagram.empty, loading, failed, nodeHelp and edgeHelp; see the components README. Includes React Flow CSS. Uses application primary/card/foreground/border tokens in light and dark themes. Ordinary edges are subdued, solid and labeled directly on the route. Set visited on nodes/edges for actual history and highlighted for the current node or available edges; current nodes have a stronger fill and ring. ELK optimizes port order to reduce crossings. Decorative nodes/edges are not focusable or selectable.
243
243
 
244
244
  ### lifecycle-diagram
245
245
 
@@ -251,7 +251,7 @@ Theme-aware, read-only lifecycle diagram using React Flow and ELK. Shows the cur
251
251
  - Plugin dependencies: none
252
252
  - Also installs: `@nocobase/flow-diagram`
253
253
  - Example: `@nocobase/lifecycle-diagram-demo` (`pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`)
254
- - After installing: Pass description.description from useLifecycle/createLifecycleHook, currentState from view.record, availableTransitions filtered from view.available, and history from view.history.transitions. History matches the exact transition/source/destination; current state alone never implies a visited path. Pass a translated endLabel for separate decorative markers on explicit final states. For detailed page diagrams use direction DOWN and autoHeight. Translate ariaLabel, stateLabel and transitionLabel; append a gear to automatic transition labels if needed. Edges are solid with inline labels and subdued neutral strokes; current/visited/available highlights use the application primary theme token. Current nodes have a stronger fill and ring, visited nodes a light fill, with no extra visited label. onStateClick/onTransitionClick open details and never fire transitions. Keep toMermaid for documentation/export.
254
+ - After installing: Pass description.description from useLifecycle/createLifecycleHook, currentState from view.record, availableTransitions filtered from view.available, and history from view.history.transitions. History matches the exact transition/source/destination; current state alone never implies a visited path. Pass a translated endLabel for separate decorative markers on explicit final states. Defaults to direction DOWN and autoHeight for vertical page reading. Override direction and autoHeight explicitly for compact canvases. stateActions supplies explicit configuration buttons; nodeDescription displays real policy summaries. Translate ariaLabel, stateLabel and transitionLabel; append a gear to automatic transition labels if needed. Edges are solid with inline labels and subdued neutral strokes; current/visited/available highlights use the application primary theme token. Current nodes have a stronger fill and ring, visited nodes a light fill, with no extra visited label. onStateClick/onTransitionClick open details and never fire transitions. Keep toMermaid for documentation/export.
255
255
 
256
256
  ## Inbox
257
257
 
@@ -77,7 +77,7 @@ Structure, top to bottom: PageHeader (primary action "New X") → toolbar (searc
77
77
  - **T3.1 [Must]** Choosing the container: with at most 8 fields and no complex dependencies between them, use a dialog — a plain Dialog `sm:max-w-md` for 1–4 fields, a `RouteDialog` for 5–8 fields or a form with a list or a picker (I1); with more fields, or when the form needs groups or steps, use a separate page (a covering child page when the user returns to the list afterwards, see I1).
78
78
  - **T3.2 [Must]** Labels sit above inputs; a required field gets a `*` after its label, and an optional field gets no mark.
79
79
  - **T3.3 [Must]** Validation timing: validate on submit, not while the form is being filled in, so a field that loses focus or a form closed without submitting shows no error. After a failed submission a field is revalidated as it changes, and its error disappears once it is corrected. Errors appear below the field and say what is wrong and how to fix it ("Enter an email address", "The email format is invalid"); when submission fails, focus moves to the first field with an error.
80
- - **T3.4 [Must]** Dialog footer buttons are right-aligned: "Cancel" and then the submit button, from left to right. On narrow screens keep the component's default: the footer of `RouteDialog` and `RouteDrawer` wraps its buttons onto another line, and `AlertDialog` stacks them vertically with the confirm button on top. The submit button names the specific action ("Create", "Save"), not "OK" or "Submit".
80
+ - **T3.4 [Must]** Dialog footer buttons are right-aligned: "Cancel" and then the submit button, from left to right. On narrow screens keep the component's default: the footers of `Dialog`, `RouteDialog` and `RouteDrawer` stack their buttons with the submit button on top, and so does `AlertDialog` with the confirm button. The submit button names the specific action ("Create", "Save"), not "OK" or "Submit".
81
81
  - **T3.5 [Must]** While submitting: the submit button shows a loading state and is disabled, the cancel button is disabled too, and the dialog cannot be closed, to prevent duplicate submissions.
82
82
  - **T3.6 [Must]** Field errors returned by the server appear below the corresponding fields; other failures appear in an Alert at the top of the form. On failure, do not close the form or clear the input.
83
83
  - **T3.7 [Must]** On success, close the dialog, update the related data (see R2) and state the result in a toast (`Created customer "Zhang San"`).
@@ -117,7 +117,7 @@ Kanban boards, calendars and similar pages have no template yet. When designing
117
117
  | Large read-only content (a transcript, a diff, a file preview) | Dialog | `sm:max-w-4xl` | scrolling body |
118
118
  | A few options, filter conditions, quick actions | DropdownMenu or Popover | sized to its content (I13) | — |
119
119
 
120
- Every confirmation is an AlertDialog, never a Dialog with two buttons. A dialog that is not a route overlay and whose content can outgrow the screen caps its height with one idiom, `max-h-[calc(100dvh-2rem)]`, keeps its header and footer fixed and scrolls only its body, so the footer's buttons never scroll out of view (A4): `DialogContent className='flex max-h-[calc(100dvh-2rem)] flex-col sm:max-w-2xl'` around a body of `-mx-4 min-h-0 flex-1 overflow-y-auto px-4` ([`references/overlay.md`](references/overlay.md#6-plain-dialogs-sizes-and-scrolling)). Do not use other caps (`90vh`, `85dvh`, `calc(100svh-2rem)`), and do not scroll the whole dialog. `RouteDialog` and `RouteDrawer` already do this.
120
+ Every confirmation is an AlertDialog, never a Dialog with two buttons. A dialog that is not a route overlay and whose content can outgrow the screen caps its height with one idiom, `max-h-[calc(100dvh-2rem)]`, keeps its header and footer fixed and scrolls only its body, so the footer's buttons never scroll out of view (A4): `DialogContent className='flex max-h-[calc(100dvh-2rem)] flex-col sm:max-w-2xl'` around a body of `-mx-6 min-h-0 flex-1 overflow-y-auto px-6` ([`references/overlay.md`](references/overlay.md#6-plain-dialogs-sizes-and-scrolling)). Do not use other caps (`90vh`, `85dvh`, `calc(100svh-2rem)`), and do not scroll the whole dialog. `RouteDialog` and `RouteDrawer` already do this.
121
121
 
122
122
  Stacking rules: a drawer can open a dialog (for example, to edit from the detail view) and a confirmation dialog; a dialog can open only a confirmation dialog on top of it. Esc and clicking the backdrop close only the topmost layer. Edit opened from a list row's menu is the dialog alone over the list; edit opened from the detail drawer stacks the dialog on the drawer, and closing it returns to the drawer; edit opened from the header of a record page with tabs stacks the dialog on the tab being shown, and closing it returns to that tab.
123
123
 
@@ -1,6 +1,6 @@
1
1
  # Configurable lifecycle parameters
2
2
 
3
- Use this when administrators need to adjust approval departments, reviewers, thresholds, reopening windows or other business values while developers keep the workflow in source. Read [record lifecycles](lifecycle.md) first. This capability belongs to `@nocobase/lifecycle`; verify that the installed package exports `StoredLifecycleParameters` and `normalizeReviewerSelections` before using it. An older installation needs a compatible release upgrade rather than invented APIs.
3
+ Apply this by default whenever building or iterating on a process with administrator-owned business policy, including approval departments, reviewers, thresholds or reopening windows. Inspect the business rules and proactively declare suitable configuration even when the user never asks for configurability; follow [system settings delivery](system-settings.md#discover-configurable-business-rules-by-default). Developers keep the workflow structure in source. Read [record lifecycles](lifecycle.md) first. This capability belongs to `@nocobase/lifecycle`; verify that the installed package exports `StoredLifecycleParameters` and `normalizeReviewerSelections` before using it. An older installation needs a compatible release upgrade rather than invented APIs.
4
4
 
5
5
  ## Code declaration and storage
6
6
 
@@ -72,11 +72,11 @@ Register selectors with `resolveReviewerSelections(choices, { scope, applicantId
72
72
 
73
73
  On task creation resolve the snapshot or live rule against current organization data and persist candidates on the task. Existing candidates stay fixed. A single approver field is not a multi-person approval system. To demonstrate multiple candidates, declare a separate finite “any candidate can decide” workflow and use version checks so only one concurrent decision succeeds. Real approval plugins need their own compatibility verification for action replay, settings previews, task construction and opinion reuse; fixed current-round tasks or inherited opinions cannot stand in for rule configuration.
74
74
 
75
- ## Optional user interfaces
75
+ ## Default configuration interfaces
76
76
 
77
- Respect the user's existing UI and scope. API-only work needs no configuration page or diagram. An existing settings page can embed a form. Offer a central page or optional bound diagram entry only when useful. Do not add a mandatory diagram or a second workflow-design system.
77
+ Deliver a configuration entry as part of the process application, without waiting for a separate request. Reuse the existing settings surface and standard definition diagram; explicitly requested API-only work or an explicit omission needs no UI. Keep workflow structure source-owned.
78
78
 
79
- When building a page with configurable parameters tied to business process nodes, prefer an editing entry on the corresponding diagram node or transition. For example, clicking a finance-review node can open a dialog for its reviewer rules and approval threshold, so users can adjust those values in their process context. If the page already includes a diagram, incorporate this entry as part of the page design; if a diagram has not been requested, suggest this interaction when discussing the process interface. Parameters with no node or transition relationship can stay in an embedded form or settings page.
79
+ When building a page with configurable parameters tied to business process nodes, provide an editing entry on the corresponding diagram node or transition. For example, clicking a finance-review node can open a dialog for its reviewer rules and approval threshold, so users can adjust those values in their process context. If the page already includes a diagram, incorporate this entry as part of the page design; include the standard definition diagram and its bound editing entries as part of system settings delivery without requiring the user to ask. Parameters with no node or transition relationship can stay in an embedded form or settings page.
80
80
 
81
81
  For save request IDs, follow the [browser request ID guidance](lifecycle.md#5-the-page): use an HTTP-compatible generator and retain the key for retries of the same save.
82
82
 
@@ -92,4 +92,4 @@ Show field titles, units, validation, read mode and effective timing. Snapshot c
92
92
 
93
93
  Test complete schemas and cross-field constraints, CAS/replay, reference scope and authorization before validation. Prove draft previews create no facts, first submission freezes every snapshot field, failed transactions/savepoints remove it, resubmission retains it, and missing historical fields fail. Check same-record actions/nested transitions share values while different records do not. Prove fresh live retries preserve business idempotency and record each attempt's facts.
94
94
 
95
- Exercise reviewer intersections/unions, duplicate and inactive/applicant filtering, changed department choices, changed organization membership and fixed existing candidates. Test simultaneous decisions. For chosen UI entry points verify shared save behavior, read-only rendering, preserved conflict drafts, multi-field bindings, untouched unbound entries and distinct current/history labels in the running application. Use the normal testing helpers and run skills sync after installation so this reference is reachable from the normal Skill entry.
95
+ Exercise reviewer intersections/unions, duplicate and inactive/applicant filtering, changed department choices, changed organization membership and fixed existing candidates. Test simultaneous decisions. For the delivered UI entry points verify shared save behavior, read-only rendering, preserved conflict drafts, multi-field bindings, untouched unbound entries and distinct current/history labels in the running application. Use the normal testing helpers and run skills sync after installation so this reference is reachable from the normal Skill entry.
@@ -2,7 +2,7 @@
2
2
 
3
3
  Use `@nocobase/lifecycle` when a business record moves through stages that developers define in source: an expense report, a ticket, a contract, an order, a leave request. The record keeps its state in one of its own fields, every change is a transition declared in a definition, and the work a transition owes outside the database — mail, payments, calls to other systems — runs as effects after the transaction commits. There is no separate process instance, so the state is never kept in two places.
4
4
 
5
- Administrators can adjust code-declared business parameters without editing workflow structure. For configurable approval departments, reviewer choices, thresholds, snapshot/live reads and optional configuration editors, read [configurable lifecycle parameters](lifecycle-parameters.md).
5
+ Administrators can adjust code-declared business parameters without editing workflow structure. Proactively declare suitable approval departments, reviewer choices and thresholds as business parameters, even without an explicit configurability request. For declarations, snapshot/live reads and shared configuration editors, read [configurable lifecycle parameters](lifecycle-parameters.md).
6
6
 
7
7
  ## Choose it or something else
8
8
 
@@ -16,11 +16,11 @@ Administrators can adjust code-declared business parameters without editing work
16
16
 
17
17
  A parent and its children can each have a lifecycle and point at each other by foreign key, such as a document and the tasks it distributes; a child's last transition can move the parent on in the same transaction.
18
18
 
19
- ## Ask about the process UI
19
+ ## Include process administration automatically
20
20
 
21
- When developing a lifecycle, ask whether the user wants to display a flowchart or a related process interface, unless they have already stated their preference. For example, ask in the user's language: “Would you like this process to include a flowchart or a process interface showing its current state, available actions and history? If yes, we can render it with the flow diagram components from our UI Library.”
21
+ Implement [the system settings delivery contract](system-settings.md) with every lifecycle: a directory of the application's real definitions, a definition diagram, supported parameter configuration and authorized execution history. Do not ask the user whether to include these administration surfaces. Use `@nocobase/lifecycle-diagram` for definitions and actual record progress, with the standard `@nocobase/flow-diagram` canvas beneath it. Respect an explicit request to omit the interface.
22
22
 
23
- If the user chooses yes, use the UI Library's `@nocobase/lifecycle-diagram` to render the lifecycle definition and record progress; `@nocobase/flow-diagram` is available for generic process graphs. Follow [the diagram integration guidance](#draw-an-interactive-lifecycle-diagram) and [the frontend workflow](frontend/ui-workflow.md) for the surrounding process interface. Respect separate preferences: a user may want state, action buttons and history without a diagram. If they decline both a diagram and a process interface, continue implementing the lifecycle without adding either.
23
+ The business record's page may show a diagram, state/actions/history, or a compact summary according to the task. This choice does not remove its administration entry. Preserve record-level permissions and source-owned structure; a definition diagram never fires a transition. Follow [diagram integration](#draw-an-interactive-lifecycle-diagram) and the [frontend workflow](frontend/ui-workflow.md).
24
24
 
25
25
  ## Rules that are never broken
26
26
 
@@ -439,13 +439,13 @@ The installed package's README lists its entries; the full guide, design notes a
439
439
 
440
440
  ## Draw an interactive lifecycle diagram
441
441
 
442
- When building a process page whose configurable business parameters relate to nodes or transitions, prefer an entry on the corresponding diagram element that opens a parameter-editing dialog. Map the clicked state's or transition's stable name through code-declared parameter bindings and open the same editor used by the settings page or embedded form, if present. A bound entry can expose several groups; unbound entries keep their ordinary details. Read [configurable lifecycle parameters](lifecycle-parameters.md#optional-user-interfaces) for the working example, authorization, CAS conflicts and current-versus-historical values.
442
+ When building a process page whose configurable business parameters relate to nodes or transitions, provide an entry on the corresponding diagram element that opens a parameter-editing dialog. Map the clicked state's or transition's stable name through code-declared parameter bindings and open the same editor used by the settings page or embedded form, if present. A bound entry can expose several groups; unbound entries keep their ordinary details. Read [configurable lifecycle parameters](lifecycle-parameters.md#default-configuration-interfaces) for the working example, authorization, CAS conflicts and current-versus-historical values.
443
443
 
444
444
  When a page needs a lifecycle diagram, use the UI Library's `@nocobase/lifecycle-diagram` component (React Flow + ELK) instead of building a canvas or turning Mermaid source into an interactive view. Read `pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`, then install with `yes n | pnpm exec shadcn add @nocobase/lifecycle-diagram` and format the created files. It includes `@nocobase/flow-diagram`, which is also available alone for a generic directed graph. Follow [the UI Library guidance](frontend/references/styling.md#3-use-shadcn) and its [offline catalog](frontend/references/ui-library.md) for discovery and installation.
445
445
 
446
446
  Import `LifecycleDiagram` from `#components/lifecycle-diagram`. Pass the hook's `description.description`, an `ariaLabel`, `currentState: view.record.status` (use the lifecycle's own state field), and `availableTransitions: view.available.filter((item) => item.allowed).map((item) => item.name)`. Translate labels by stable state/transition names with `stateLabel` and `transitionLabel`; add the shared `flowDiagram` keys to your locale resources. Use `onStateClick` and `onTransitionClick` to open details, including effects, triggers and continuations from the description. Definitions remain in source and clicking the diagram never fires a transition; action buttons still follow `view.available`. Pass `history={view.history.transitions}` for visited paths; the component matches the exact transition, source and destination, including retries. `visitedStates` supplements node highlights only; never infer a traversed edge from the current state or visited endpoints. Pass a translated `endLabel` to display a separate decorative end marker after each explicit final state, without treating every state lacking outgoing transitions as final. Keep `toMermaid()` for documentation and export.
447
447
 
448
- For detailed page diagrams, prefer `direction="DOWN" autoHeight`: the canvas grows with the full layout, including outer routes and labels. A wide graph fitted into a short fixed-height panel makes its labels unreadable. Check the actual lifecycle definition in the target page, rather than judging a simple preview alone.
448
+ `LifecycleDiagram` defaults to `direction="DOWN" autoHeight`. For direct `FlowDiagram` composition on a process page, set those props explicitly: the canvas grows with the full layout, including outer routes and labels. A wide graph fitted into a short fixed-height panel makes its labels unreadable. Check the actual lifecycle definition in the target page, rather than judging a simple preview alone.
449
449
 
450
450
  The label callbacks receive description objects, not name strings. Read `state.name` in `stateLabel` and `transition.name` in `transitionLabel` when building translation keys:
451
451
 
@@ -457,3 +457,5 @@ transitionLabel={(transition) => t(`leaves.transitions.${transition.name}`)}
457
457
  Adapt the translation key prefix to the feature.
458
458
 
459
459
  Preserve the component’s application theme tokens: `--primary` for current, visited and available highlights, subdued neutral strokes for other edges, and card/foreground/border tokens for the canvas and labels. Current nodes have a stronger fill and ring, visited nodes a light fill, with no extra “visited” label. Labels stay on the routes; automatic transitions remain solid and may show `⚙` through `transitionLabel`. Do not introduce a separate palette or hard-coded accent color. Check light/dark themes and a changed application primary color when customizing the rendering.
460
+
461
+ For narrow layouts, use `initialMinZoom={0.8}` to preserve readable node content, with pan and a full-graph Fit control. Do not add a minimap to standard process pages by default; `showMiniMap` remains opt-in for consumers that need it. `stateActions` on LifecycleDiagram (or `nodeActions` on FlowDiagram) exposes explicit configuration buttons; `nodeDescription` adds real policy summaries. Supply enough fixed node height for the content. Definition views show the latest configured policy, while record views identify their submission snapshot. Never invent reviewer names, policy values or execution highlights. Standard business process pages omit system-only technical edit paths without adding a technical display toggle; retain every business approval, rejection, withdrawal and resubmission path. Technical diagnostic views may expose the complete source description separately when explicitly needed.
@@ -238,7 +238,8 @@ Do not write a helper that mutates a router passed in by its caller. Returning a
238
238
  A route that answers many rows or figures reads them with a fixed number of queries, whatever the row count. The database API is in the `nocobase-db` Skill.
239
239
 
240
240
  - Read each kind of data once for all rows: one query with `IN (...)` over the row ids, then join the results in memory. Never call a per-item function or Repository read inside a loop or a `Promise.all` over rows.
241
- - A list row carries only what the row shows. Expensive per-item work — diagnostics, "why is this waiting", full histories — belongs to the item's own detail endpoint.
241
+ - When per-item database work genuinely cannot be batched, bound its concurrency to a small number rather than starting one query per item at once: an unbounded `Promise.all` can exhaust the connection pool and stall every other request, not just this one.
242
+ - A list row carries only what the row shows. Expensive per-item work — diagnostics, "why is this waiting", full histories — belongs to the item's own detail endpoint, which the client usually reads when a detail view opens. When you add a field to a list response, check how much it adds to the response size across a full page of rows.
242
243
  - A component that needs one small fact, such as whether the viewer follows an item, gets a small endpoint answering that fact rather than reading a whole list or overview.
243
244
  - Aggregate in the database: `COUNT`, `SUM`, `GROUP BY` through the Repository's `count`/`groupBy` or the query builder. Never load rows to count or sum them in JavaScript.
244
245
  - One chart is one request, so charts load, fail, refresh and cache on their own. Each chart's request computes its figures with a fixed number of aggregate queries: one `GROUP BY` day, not a query per day or per item.
@@ -248,6 +249,14 @@ A route that answers many rows or figures reads them with a fixed number of quer
248
249
 
249
250
  The browser side — refreshing such a list or chart from realtime events — is in [client API requests](frontend/references/api.md#keeping-lists-and-charts-live).
250
251
 
252
+ ## Frequently called endpoints
253
+
254
+ An endpoint called on a timer — polling, a heartbeat, a status badge every open page reads — costs its per-call price times its call frequency across every client, so a few milliseconds per call can add up to a large share of the database's time. Estimate both before writing one.
255
+
256
+ - Usually keep it read-only, without writes or a transaction. Work that has to write, such as recording last-seen times or cleaning up, can often move to a less frequent place: a scheduled job (see [services and jobs](services-and-jobs.md#work-that-runs-on-a-schedule)), or a write only when the value actually changed.
257
+ - Read-only code usually needs no transaction, here or anywhere else. A transaction holds a connection for its whole duration and can make reads cost more; use one only for writes that must succeed or fail together.
258
+ - Prefer answering a small fact over a list or overview, as the section above describes, and consider caching it briefly when many clients ask the same question.
259
+
251
260
  ## Keep the layers apart
252
261
 
253
262
  Routes handle HTTP: parsing input, checking permission, shaping the response and status. Domain logic goes in a service under `server/providers/` — see [services and jobs](services-and-jobs.md). A service should not read a Hono context or decide status codes.
@@ -281,3 +290,4 @@ In React components and custom Hooks, use `useApiClient()` from `@nocobase/app-c
281
290
  - Every `/api` route is declared: after `app.start()`, `findUndeclaredApiRoutes(app)` is empty, and the route appears in `GET /api/swagger` with its `operationId`. See the Verify section of [HTTP API design](http-api.md#verify).
282
291
  - A public route rejects missing and invalid signatures, and handles duplicate delivery.
283
292
  - A list or statistics route makes the same number of queries for ten rows as for a thousand.
293
+ - A frequently called route stays read-only and outside a transaction, or its writes have a reason to be there.
@@ -222,6 +222,16 @@ await app.container
222
222
 
223
223
  See the `@nocobase/queue` README for the full contract.
224
224
 
225
+ ## Keep background work light
226
+
227
+ Background and maintenance work shares the database and its connection pool with the requests users are waiting on, so it should usually not block them.
228
+
229
+ - Maintenance usually should not pause the main flow. Prefer work that runs beside it over a step that holds requests or other jobs until it finishes.
230
+ - Time-box long work or do it in batches: process a bounded number of rows per run or per transaction, and continue in the next run, rather than one long transaction or one query over a whole table.
231
+ - When per-item work queries the database, batch it or bound its concurrency, as [server routes](server-routes.md#lists-and-statistics-a-fixed-number-of-queries) describes for lists.
232
+ - When the inputs have not changed, consider caching the result (`cachingToken` from `@nocobase/app-server/caching`) or skipping the run rather than recomputing it.
233
+ - Leave headroom in timeouts and leases. While a worker is alive, give it enough time to finish, for example by renewing its lease; a missed heartbeat is usually a more reliable sign that a machine is gone than a tight timeout, which can declare a slow but healthy worker dead and run its work twice.
234
+
225
235
  ## Verify
226
236
 
227
237
  - The service resolves from the token and behaves correctly in isolation.
@@ -0,0 +1,83 @@
1
+ # Deliver system settings with the capability
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.
4
+
5
+ ## Baseline
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.
8
+
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. 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
+
11
+ ## Reconcile administration on every iteration
12
+
13
+ Start from the business request and the application's real routes, models, services, parameter declarations and installed plugin Skills. Identify administrator-owned values, mutable reference data and operations whose results need tracking even when the user never mentions settings. Match each to an existing working surface before adding one. The trigger is actual business use, not a dependency, a keyword such as "configurable", or a development round.
14
+
15
+ For each applicable capability, identify its owner, persistence, authorized read/write API, management entry and execution consumer. Reuse the owning plugin's documented contracts. Where the capability is application-owned, implement its real backend, validation and UI as part of the business feature; an absent platform API is not permission to invent one. Read [business administration recipes](business-administration.md) for parameters, dictionaries, numbering and operation records. If an external prerequisite prevents a working integration, report that limitation and omit disconnected controls.
16
+
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
+
19
+ ## Capability checklist
20
+
21
+ | Actual business use | Administration to deliver automatically |
22
+ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23
+ | User accounts and business permissions | Prepared Users and Roles and permissions routes, account status and supported session controls; preserve existing role scope ownership |
24
+ | Record lifecycles, workflows or approvals | Real definitions directory, standard diagrams, declared parameters, and authorized execution records/history with business record links |
25
+ | Approval rules | Proactively declared thresholds and supported reviewer choices; organization-based approval also needs its real department/manager relationships; personal tasks stay in business navigation |
26
+ | Administrator-adjustable business policy, with or without a workflow | Typed business settings such as limits, validity windows, stock warnings and supported switches; actual decisions must read saved values |
27
+ | Administrator-maintained categories, priorities, sources or reasons | Scoped business dictionaries with stable keys, sorting, enable/disable and safe handling of referenced entries; fixed technical enums remain source-owned |
28
+ | User-visible business document numbers | Rule administration and non-consuming preview, with transactional allocation, uniqueness and replay protection; generated internal IDs remain implementation details |
29
+ | Account, role, rule or other important administrative changes | Authorized operation records backed by real server-side capture/storage, including actor, time, target and an allowlisted change summary; preserve historical scope |
30
+ | Actual department, manager, position or organization membership rules | The authoritative organization/member relationships the business consumes, with eligibility and access boundaries preserved |
31
+ | Enabled registration, enterprise sign-in, MFA or other authentication extensions | The enabled feature's supported management and account/session controls, using the authentication Skill and required migrations; source-owned security configuration stays with deployment |
32
+ | Notifications or email | Used channel status, supported message/recipient rules, administrable templates and delivery diagnostics; credentials remain server-owned |
33
+ | Uploads and attachments | Authorized file administration, supported upload policy and used storage status; deployment-owned disk configuration uses the operations boundary below |
34
+ | Scheduled business work | Task definitions/status, timezone and execution history, plus authorized enable/disable when supported; current Scheduler Cron definitions remain code-owned |
35
+ | External integrations, API access or Webhooks | Used connections, supported credential lifecycle, connection/delivery/synchronization status and failure records; respect credential ownership and actual scope enforcement |
36
+ | Business document templates or bulk import/export | Template administration where business users need to maintain templates; otherwise reuse fixed assets. Provide authorized processing results and failure details; asynchronous jobs only when the feature uses them |
37
+ | App-owned model calls, user-facing AI or managed knowledge content | The actual enabled model-service/catalog and knowledge-content surfaces, supported prompt/configuration controls and real run diagnostics; follow the owning plugin Skill |
38
+ | Shared business defaults | Persisted currency, units, reporting timezone or working-calendar settings when administrators need to change them; define their effect on calculations and existing records |
39
+
40
+ Installed dependencies alone do not mean a capability is used. Every control must have a real authorized read path and, when editable, a validated save path consumed by the business. Do not show disconnected cards, fake endpoints, invented audit/usage/cost history, demonstration identities or unavailable plugins. Never automatically issue API keys, enable external services or expose credentials. The default API-key endpoints manage the caller's own keys; a Settings page does not grant an administrator access to everybody's keys or imply per-key scope enforcement.
41
+
42
+ ## Application and operations ownership
43
+
44
+ Place business administration in the application, grouped under existing Settings navigation where appropriate. Keep operational task details with their feature, personal account/appearance preferences in the account/header surfaces, and customers, suppliers and products in their business modules rather than treating all master data as system configuration. Offer one shared editing contract when both a contextual entry and a central settings entry exist.
45
+
46
+ Reuse the actual Host, Hub or deployment workflow for database connections, server/storage credentials, secrets keys, deployment, backup/restore and platform-wide operations. Configuration declared in source or environment remains source/deployment-owned unless its installed runtime explicitly supports safe dynamic updates. An App can expose an authorized masked status or existing operations link; do not generate a second infrastructure control plane or a save button over values requiring redeployment. Default language/theme at startup and each user's saved choices retain their existing precedence.
47
+
48
+ ## Workflow integration
49
+
50
+ For an application-owned lifecycle, register the real descriptions explicitly in one application provider. Expose an authenticated, authorized catalogue and definition detail endpoint, using schema allowlists and the standard API envelope. Never serialize the runtime, closures, credentials or execution contexts. Build one process-management directory under the application's Settings navigation group using the standard `DataTable`, even when only one process is registered. Never redirect the directory straight into that one definition. List the actual registered processes with stable identifiers, localized names, types and useful runtime-derived metadata; provide search, bounded pagination and supported sorting. Each process opens its own URL-addressable detail with `Definition` and `Execution records` sections. Keep node configuration on the corresponding state or transition, and link each execution to its real business record, progress, decisions and diagnostic history as supported by that runtime. Preserve list filters and pagination when returning from detail or an overlay. Later development adds new registered processes to this same directory instead of creating a separate menu for each one. Use `@nocobase/lifecycle-diagram`, which installs the standard `@nocobase/flow-diagram` canvas, rather than a bespoke bare React Flow view. Source-defined structure is read-only; proactively declared business parameters are edited through their authorized service as described below.
51
+
52
+ Catalogue entries must explicitly bind their runtime definition, record collection, read permissions and execution adapter. Validate the process identifier on definition, parameter and execution endpoints; reject unknown identifiers and never fall back to another process's records. Filter by the selected process and enforce its business scope before counting or paging. Do not fabricate enable/disable, publish, edit-topology or delete controls when the installed runtime does not support them.
53
+
54
+ Definition read, parameter update and execution visibility are distinct permissions. Execution queries must preserve the owning business record's data scope. Link definitions to their authorized executions and executions back to their real records. Reuse revision checks, snapshot/live reads and parameter editors. An application with no process runtime has no empty workflow administration API or menu. If a workflow/approval plugin supplies its own catalogue contracts, read its installed Skill and adapt those contracts instead of assuming lifecycle APIs apply to it.
55
+
56
+ ### Default process presentation
57
+
58
+ When business development introduces approvals or process orchestration, deliver the process-management directory, definition/design page, supported node configuration and authorized execution records in the same feature, even when the user never asks for system settings or configurability. A single process still opens from the standard table. Keep bare Home-only create-app output free of unused settings; reconcile this contract whenever capabilities change, independently of the iteration number.
59
+
60
+ Use a vertical, top-to-bottom definition by default: `LifecycleDiagram` defaults to `direction="DOWN" autoHeight`, and direct `FlowDiagram` composition sets these props explicitly. Grow the page with the complete routed layout instead of fitting a wide graph into a short fixed-height panel. Keep the main business stages in order, conditional paths beside them and return paths outside the main path as the layout permits; preserve every real approval, rejection, withdrawal and resubmission connection. Keep node labels, saved threshold/reviewer summaries and localized configuration buttons readable with semantic theme tokens. Do not add an overview minimap or technical edit-path toggle by default. A compact record progress view may explicitly choose another orientation or bounded height when appropriate. Verify the real graph, long labels and narrow widths, not only a simple demo. Diagram structure remains source-owned; “process design” does not imply unsupported drag editing or topology writes.
61
+
62
+ ## Discover configurable business rules by default
63
+
64
+ Whenever building or changing business behavior, inspect its conditions, limits, reviewer selection and existing configuration declarations. For processes, also inspect routing and guards. The user does not need to say "configurable". Proactively turn administrator-owned business policy into real declared parameters. Bind process fields to the consuming state or transition and expose other policy through its appropriate business settings entry. Reconcile this on every iteration, reusing stable group and field keys rather than adding duplicate settings.
65
+
66
+ | Business policy found while building | Default configuration to provide |
67
+ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
68
+ | Approval, amount, quantity or score thresholds | Typed numeric fields with labels, units, bounds and cross-field validation; preserve the requested policy as the initial default |
69
+ | Reviewer selection by person, role or department | A real scoped directory picker and the runtime's supported reviewer rules, backed by server-side eligibility checks |
70
+ | Business windows such as a reopening period | A bounded duration with explicit units and effective timing, where the installed runtime supports updating it |
71
+ | Notification copy or an existing supported business switch | The declared editable text or boolean, with the actual delivery or decision path reading the saved value |
72
+
73
+ For lifecycles, use the installed runtime's `parameterConfiguration`, store, service and editor contracts; read [configurable lifecycle parameters](lifecycle-parameters.md). For policy outside a lifecycle, use the application's existing configuration service or implement the application-owned contract in [business administration recipes](business-administration.md#business-parameters); lifecycle-only APIs are not a generic settings service. Declare defaults, schema, validation, bindings, authorization and snapshot/live behavior together. The server's actual route, reviewer resolver or business decision must consume the saved values. An editable form over a hard-coded condition does not satisfy this requirement. Reuse authoritative organization and account data; never guess an approver or substitute demonstration people. A single-assignee workflow must keep its decision semantics unless multi-candidate decisions are implemented and verified.
74
+
75
+ For lifecycles, expose bound fields automatically from the standard definition diagram. States and transitions with real bindings expose an explicit localized Configure control on the corresponding element, opening the shared editor or authoritative relationship settings; configuration read without update permission remains read-only. Preserve ordinary inspection for unbound elements. The same stored configuration powers any central settings page and diagram entry. Do not ask whether to add the diagram or parameter entry when delivering a process application, unless the user explicitly requests API-only work or omits the interface.
76
+
77
+ For approval policy, default to snapshot semantics for a formal submission unless the business requirement calls for live changes. Explain when a saved change takes effect; existing submitted snapshots, assigned candidates and historical facts remain fixed. Technical constants, authorization guards, workflow topology, credentials, payment identities and code-owned trigger scheduling are not inferred as editable business parameters. A timing field is editable only when the runtime explicitly supports its scheduling semantics. Preserve valid existing values and revisions when adding new bindings; handle already submitted records through the lifecycle's documented compatibility policy.
78
+
79
+ ## Delivery checks
80
+
81
+ Check every applicable row above, not just the capability named by the user. Include a concise delivery map in the development report: capability, working entry, owning persistence/API, permission, execution consumer, and observed evidence or explicit limitation. Read [acceptance scenarios](business-administration.md#acceptance-scenarios) for blind-prompt and iteration checks. This is development evidence, not implementation detail to display to application users.
82
+
83
+ Before finishing, map each used capability to its working management entry, route, real API, server-side permission and verification evidence. Group entries under the existing Settings route; hide an empty group after permission filtering. Repeated additions reconcile missing entries only: no duplicate menus, role seeds or configuration. Preserve existing stable route ids and unrelated administrator grants. Verify an authorized administrator, a user without management access, direct API denial, loading/empty/error states, write failure, deep links, Chinese/English, dark/light and narrow layouts. Keep execution data current through the existing realtime mechanism or a working Refresh action. For inferred threshold and reviewer parameters, save a different valid configuration and prove that a new eligible business execution uses it; also verify invalid values, an unauthorized update, snapshot preservation and repeated iterations without duplicate fields or bindings.
@@ -6,7 +6,7 @@ A template not listed here is still supported. Derive its capabilities from the
6
6
 
7
7
  ## Default
8
8
 
9
- `@nocobase/app-template-default` is the clean application starting point. It begins with a localized homepage, required permission initialization, no application-owned business routes or services, no example plugins, and no demo data. Its Users integration exposes Authorization Permission Sets as direct application roles. Preserve this clean boundary when editing the template itself; runnable demonstrations belong in Examples.
9
+ `@nocobase/app-template-default` is the clean application starting point. It begins with a localized homepage, prepared but unregistered Users and Roles and permissions page modules, required permission initialization, no application-owned business routes or services, no example plugins, and no demo data. Its Users integration exposes Authorization Permission Sets as direct application roles. Do not display system settings on bare create-app: reconcile the prepared core settings contribution as the application develops business capabilities, and supply administration for capabilities actually used on every iteration. Preserve this clean boundary when editing the template itself; runnable demonstrations belong in Examples.
10
10
 
11
11
  ## Examples
12
12
 
@@ -118,6 +118,20 @@ Component tests, the route test and translation checks are described in [fronten
118
118
 
119
119
  Run against a real test database. A test that only imports the migration file proves nothing about the schema it produces. `describeMigration()` from `@nocobase/app-testing/server` applies the migrations before it, applies this one, rolls it back and applies it again, and checks after each step that metadata and tables agree and that rolling back restores every table as it was; its `up` and `down` callbacks verify the fields, indexes and constraints with `expectCollection()`.
120
120
 
121
+ ## Keeping the suite fast and honest
122
+
123
+ These are habits, not rules to apply mechanically; when the suite gets slow, measure where the time goes first (building, migrating, waiting, starting servers) and fix the largest part.
124
+
125
+ - **Test at the cheapest layer that proves the behavior.** A browser test earns its cost for what only a real browser shows: a flow across pages, real input, history and focus. Loading, error and empty states, copy, and combinations of locale, theme or role belong in component or unit tests. When a browser test is removed, name the test that now covers it.
126
+ - **Migrate once, not per test.** A suite whose every test needs a freshly migrated database can pass `template: true` to `createTestDatabase()`: it migrates and seeds once and gives each test a copy. Re-running every migration per test is usually most of a slow server suite.
127
+ - **Do not wait for real time.** Make retry back-offs, sweep or poll intervals and cache lifetimes configurable and set them short in tests, or use fake timers (`vi.useFakeTimers()`, Playwright's `page.clock`). Hold a mocked response open until the step that needs it instead of adding a fixed delay, and never sleep to show that nothing happened.
128
+ - **Keep tests independent.** Give a test its own user rather than changing a shared account's language, theme or settings. Start a separate application only for a test that changes global settings, and stop it at once afterwards. Let background work and the connection pool settle before closing a test database.
129
+ - **Assert, do not collect evidence.** A test checks behavior; it does not save screenshots or report files or print logs. Screenshots meant for people to look at are a separate run outside routine CI, and still fail on page errors.
130
+ - **Do not check the same thing twice.** Do not copy the framework's or the template's own tests into the application, do not snapshot what a dedicated check already compares (the API document, generated references), and replace a large snapshot nobody reads with assertions on the few figures that matter.
131
+ - **Remove tests with what they cover, and do not guard absences.** When a feature, page, route or option goes away, delete or rewrite its tests in the same change instead of leaving them to test a stub. Do not add tests that prove something removed stays removed (a deleted route still answers 404, an old translation key never returns, a file no longer contains a string): they protect nothing anyone relies on and outlive their reason. The same goes for tests written as one-off evidence for a task, and for tests of a document's or a Skill's wording.
132
+ - **Test behavior, not implementation details.** Assert what a user or caller observes, not exact internal call counts, private helpers, timer values patched by delay or full copy that is not the subject of the change; such tests break on every refactor and catch nothing.
133
+ - **Match parallelism to the machine.** More workers than cores, or a server and browsers competing for the same cores, make each test slower rather than the suite faster.
134
+
121
135
  ## Before finishing
122
136
 
123
137
  Scope every check to the changed behavior and its affected consumers. Select relevant checks rather than running a fixed full-application checklist after each edit:
@@ -142,6 +156,8 @@ Then verify the affected behavior, selecting only the applicable steps below. Gr
142
156
  - Confirm the endpoint's responses for signed-out, unpermitted, and permitted callers.
143
157
  - Confirm `pnpm nocobase db apply` applies cleanly.
144
158
 
159
+ When a change is about performance, or adds a list, a statistic or a frequently called endpoint, measure it in a realistic environment: the database the application is actually deployed on, with a realistic data volume. A small data set hides slow queries and missing indexes, and SQLite's costs differ from those of a database server, so a timing on one says little about another. After release, consider each endpoint's call count multiplied by its duration rather than a single measurement: a cheap endpoint called constantly can cost more than a slow one called rarely.
160
+
145
161
  ## Reporting
146
162
 
147
163
  Say what you ran, what passed, and what you did not run. If you could not verify something — no test database, a flow needing real credentials — say so rather than implying it was checked.
@@ -229,3 +229,7 @@ NocoBase Hub is discontinued, and with it `@nocobase/hub-cli` and the `pnpm noco
229
229
  2. Delete `.nocobase/hub.json` and the `HUB_*` variables in `.env` and any example environment file.
230
230
  3. Tell the user which CI steps and scripts published to a Hub, and that they need another deployment route: a deployment archive from `pnpm build --tar` installed with `@nocobase/app-installer`, or the application's `Dockerfile`, as the `nocobase-deployment` Skill describes. Ask before rewriting a pipeline; do not delete one silently.
231
231
  4. Ask the user to remove the saved Hub API keys from their credentials file themselves; never read or print them.
232
+
233
+ ## Permission editor source upgrades
234
+
235
+ When the target template changes the permission workspace, reconcile `client/components/permission-editor.tsx`, its `permission-filter.tsx` input and declared UI primitives (including `checkbox` and `popover`), `client/pages/settings/permissions-model.ts`, the role form callback bindings, `permission-filters.tsx` and localized labels together. Resource rows use action checkboxes with scopes attached to their owning action; scope controls are not additional permissions. The optional `onEnabledBatchChange` reports one atomic batch for visible toggleable actions; bind it with one functional draft update that retains unknown grants, policies and scopes. Existing consumers without that callback retain individual action editing. Preserve application-specific resource registration, protected roles, save/revision checks and server authorization. Include a multi-action selection test and a test retaining existing scope policies. Registry source copies do not update themselves when the registry site publishes; bring this interaction in through the template source merge, preserving application customizations.
@@ -5,7 +5,7 @@ description: Plan, build, deploy, verify, upgrade, and troubleshoot NocoBase 3 a
5
5
 
6
6
  # NocoBase production deployment
7
7
 
8
- Use this Skill to execute a complete deployment workflow. Read the application's `AGENTS.md`, the `.agents/rules/` files it indexes for building and deployment, and `README.MD` before changing files or running stateful commands: the README documents this application's build targets, archive layout and configuration variables. The Deployment section of the NocoBase 3 documentation is the reference for command details and platform-specific examples; in the nocobase3 source repository it is `docs/docs/<lang>/deployment/`.
8
+ Use this Skill to execute a complete deployment workflow. Read the application's `AGENTS.md`, the `.agents/rules/` files it indexes for building and deployment, and `README.MD` before changing files or running stateful commands: the README documents this application's build targets, archive layout and configuration variables.
9
9
 
10
10
  Do not treat a process being healthy as proof that the application is usable. A deployment is complete only after the database, configuration, application behavior, and persistence checks below have evidence.
11
11
 
@@ -99,7 +99,7 @@ npx --registry=https://registry.npmjs.org @nocobase/app-installer@beta install /
99
99
  npx --registry=https://registry.npmjs.org @nocobase/app-installer@beta upgrade --dir /srv/nocobase/crm --archive /tmp/crm.tar.gz
100
100
  ```
101
101
 
102
- Published product applications can also be deployed with an app-installer version whose `--help` offers `--app`: `install /srv/nocobase/studio --app @nocobase/studio@beta` explicitly selects the beta channel. This route needs pnpm 11+ and builds the published package on the server without a repository checkout, preserving its identity and version. An npm installation upgrades the same package with `upgrade --dir <root> --to beta`, an explicitly requested `--to <version or tag>`, or `--rebuild` (installed version). Read `source.kind` in `status` before choosing the upgrade command; an archive installation still needs `--archive`. The same persistent configuration, backup and rollback rules apply.
102
+ Published product applications can also be deployed with an app-installer version whose `--help` offers `--app`: `install /srv/nocobase/crm --app @acme/crm@beta` explicitly selects the beta channel. This route needs pnpm 11+ and builds the published package on the server without a repository checkout, preserving its identity and version. An npm installation upgrades the same package with `upgrade --dir <root> --to beta`, an explicitly requested `--to <version or tag>`, or `--rebuild` (installed version). Read `source.kind` in `status` before choosing the upgrade command; an archive installation still needs `--archive`. The same persistent configuration, backup and rollback rules apply.
103
103
 
104
104
  `install --base-path /crm` chooses the mount path and writes it to `app.env` as `APP_BASE_PATH`; without it the server default `/main` applies. Upgrades keep the path `app.env` names, and editing it there moves the application on its next start. The installer refuses an archive for another application, an older version or another machine. The same version built again deploys as a new release, so the version need not be bumped for each deployment. An archive from an `@nocobase/app-cli` that predates relocatable builds has its mount path compiled in and runs only at that path, so a mismatch is refused with `BASE_PATH_MISMATCH`; one older still, which records no build time, or a release whose `@nocobase/app-server` predates `APP_STORAGE_DIR`, is refused: upgrade the project's NocoBase packages and build again. Each application on the server gets its own directory, port and pm2 process.
105
105