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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.35",
3
+ "version": "0.1.0-beta.36",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -79,29 +79,30 @@ The handbook's "Look up by task" table routes each frontend task to the sections
79
79
 
80
80
  Read the page for the task in front of you. Do not read all of them.
81
81
 
82
- | Task | Read |
83
- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
84
- | 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
- | Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
86
- | 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
- | Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
88
- | Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
89
- | Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
90
- | Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md) |
91
- | Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md) |
92
- | Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
93
- | Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
94
- | A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
95
- | Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source. When building process pages with node-related parameters, prefer an editing dialog opened from the corresponding diagram node or transition. |
96
- | Flowcharts, process diagrams or lifecycle state diagrams | Use UI Library `@nocobase/flow-diagram` for generic graphs and `@nocobase/lifecycle-diagram` for lifecycle descriptions; see [diagram guidance](references/lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [UI catalog](references/frontend/references/ui-library.md#diagrams). Preserve their application theme tokens. |
97
- | Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
98
- | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
99
- | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
100
- | Where a file goes, how the client and server are composed, configuration, changing the framework structure | [application structure](references/app-structure.md) |
101
- | Register, update, customize or remove a plugin; check what an installed plugin already provides | [plugins](references/plugins.md) |
102
- | Add an npm package, decide `dependencies` versus `devDependencies`, diagnose a missing module or native binary | [adding a dependency](references/dependencies.md) |
103
- | Report the application's URL, dev server restarts and file watching, develop against another backend | [the development server](references/dev-server.md) |
104
- | Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
82
+ | Task | Read |
83
+ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
84
+ | 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
+ | Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
86
+ | 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) |
88
+ | Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
89
+ | Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
90
+ | Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
91
+ | Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md) |
92
+ | Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md) |
93
+ | Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
94
+ | Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
95
+ | A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
96
+ | Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source. When building process pages with node-related parameters, prefer an editing dialog opened from the corresponding diagram node or transition. |
97
+ | Flowcharts, process diagrams or lifecycle state diagrams | Use UI Library `@nocobase/flow-diagram` for generic graphs and `@nocobase/lifecycle-diagram` for lifecycle descriptions; see [diagram guidance](references/lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [UI catalog](references/frontend/references/ui-library.md#diagrams). Preserve their application theme tokens. |
98
+ | Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
99
+ | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
100
+ | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
101
+ | Where a file goes, how the client and server are composed, configuration, changing the framework structure | [application structure](references/app-structure.md) |
102
+ | Register, update, customize or remove a plugin; check what an installed plugin already provides | [plugins](references/plugins.md) |
103
+ | Add an npm package, decide `dependencies` versus `devDependencies`, diagnose a missing module or native binary | [adding a dependency](references/dependencies.md) |
104
+ | Report the application's URL, dev server restarts and file watching, develop against another backend | [the development server](references/dev-server.md) |
105
+ | Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
105
106
 
106
107
  A feature with a page and an API usually needs migrations, server routes, and a frontend change that follows the frontend workflow.
107
108
 
@@ -210,3 +210,5 @@ With multiple connections, TypeScript may omit suggestions inside an empty `dial
210
210
  Application server builds retain declaration emission with `isolatedDeclarations: false`, allowing direct default exports of configuration factory calls. The helper returns the common `AppConfigFactory<AppDatabaseConfig>` contract; its result does not expose the inferred concrete driver types. Library packages retain isolated declaration checking. `AppDatabaseConfigFromDrivers` remains available for explicit annotations outside the helper.
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
+
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.
@@ -298,6 +298,18 @@ Other points:
298
298
  - When loading through a Repository (see "Remote Repository"), the request cannot take a `signal` and cannot be aborted, but still check `controller.signal.aborted` in the callbacks to discard stale results.
299
299
  - For the complete list page (search conditions written to the URL, empty and no-results states, the `Spinner` in the toolbar while reloading), see [`table.md`](table.md) and [`example/list-page.md`](example/list-page.md); for loading the latest data before an edit form opens, see [`form.md`](form.md); for the detail drawer, see [`overlay.md`](overlay.md).
300
300
 
301
+ ## Keeping lists and charts live
302
+
303
+ When realtime events refresh what a page shows:
304
+
305
+ - An event that names items refreshes those items: gather the ids of a burst (a few hundred milliseconds), read only those rows, keep one such request in flight, and merge the answer into what the page holds. Read the whole list again only when its membership changed (an item joined or left it, or moved between its groups) or the event names nothing.
306
+ - Do not read a whole list or overview again on every event.
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
+ - Read nothing for a page that is not shown; read it when it is shown again.
309
+ - A component that needs one small fact reads the small endpoint that answers it, not the list that happens to contain it.
310
+
311
+ The server side of these reads is in [server routes](../../server-routes.md#lists-and-statistics-a-fixed-number-of-queries).
312
+
301
313
  ## Error handling
302
314
 
303
315
  ### ApiClientError
@@ -233,6 +233,21 @@ export function createOrderRoutes(options: CreateOrderRoutesOptions): Hono {
233
233
 
234
234
  Do not write a helper that mutates a router passed in by its caller. Returning a router you own keeps the security boundary inside the thing being tested.
235
235
 
236
+ ## Lists and statistics: a fixed number of queries
237
+
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
+
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.
242
+ - 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
+ - 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
+ - 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.
245
+ - Bound every statistic by a time range or a limit. A column a large table is filtered or grouped by needs an index — see [migrations](migrations.md).
246
+ - An aggregate that is expensive and read often is cached briefly with the application's cache (`cachingToken` from `@nocobase/app-server/caching`) rather than recomputed per request.
247
+ - Test it: the number of queries a list or statistics endpoint makes stays the same when the rows or groups grow. See [testing](testing.md#what-to-test-by-change).
248
+
249
+ 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
+
236
251
  ## Keep the layers apart
237
252
 
238
253
  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.
@@ -265,3 +280,4 @@ In React components and custom Hooks, use `useApiClient()` from `@nocobase/app-c
265
280
  - Middleware does not leak into other routes.
266
281
  - 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).
267
282
  - A public route rejects missing and invalid signatures, and handles duplicate delivery.
283
+ - A list or statistics route makes the same number of queries for ten rows as for a thousand.
@@ -16,15 +16,16 @@ Templates ship their tests into generated applications. Keep them runnable from
16
16
 
17
17
  ## What to test, by change
18
18
 
19
- | You changed | Test at least |
20
- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
21
- | A server route | Anonymous → `401`, authenticated but unpermitted → `403`, permitted → expected payload; the route is declared in the API document |
22
- | A public webhook | Missing signature, invalid signature, valid signature, duplicate delivery |
23
- | A migration | `up` produces the expected schema; `down` reverses it; against a real database |
24
- | A seed | First run, run against existing data, repeat run |
25
- | A service | Its domain behavior, with its dependencies supplied directly |
26
- | A job | `execute()` with a realistic payload; a second run is harmless; failures behave as intended |
27
- | Frontend code | See [frontend tests](frontend/references/testing.md): pages, components, route declarations, copy |
19
+ | You changed | Test at least |
20
+ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
21
+ | A server route | Anonymous → `401`, authenticated but unpermitted → `403`, permitted → expected payload; the route is declared in the API document |
22
+ | A list or stats route | Its query count does not grow with the number of rows or groups: count the reads for a few rows and for many, and assert they are equal |
23
+ | A public webhook | Missing signature, invalid signature, valid signature, duplicate delivery |
24
+ | A migration | `up` produces the expected schema; `down` reverses it; against a real database |
25
+ | A seed | First run, run against existing data, repeat run |
26
+ | A service | Its domain behavior, with its dependencies supplied directly |
27
+ | A job | `execute()` with a realistic payload; a second run is harmless; failures behave as intended |
28
+ | Frontend code | See [frontend tests](frontend/references/testing.md): pages, components, route declarations, copy |
28
29
 
29
30
  ## Testing a route
30
31
 
@@ -94,6 +94,8 @@ diff -rq "$WORK/$BASE" "$WORK/$TARGET"
94
94
 
95
95
  `Files ... differ` is modified, `Only in TARGET` added, `Only in BASE` removed. Read the substantive ones with `diff -u`. Use the actual BASE → TARGET changes and the project's current state to decide what applies. The target template's `@nocobase/app-skills` dependency identifies the shared guidance shipped for that release; inspect that package's relevant references when a changed framework contract needs explanation. Check [edge cases](references/edge-cases.md) for generated configuration, synchronized Skills, and migration history that the template diff cannot describe.
96
96
 
97
+ When the upgrade changes application migrations or registered plugins that supply migrations, read [database upgrades](references/database-upgrades.md) during planning, before starting the target application. Review the affected packages' upgrade notes as well as the template diff: a dependency update can change database behavior without adding a migration file to the application. Include any documented checksum correction, data prerequisite, and irreversible migration in the upgrade and recovery plan. A Git branch protects source, not the database.
98
+
97
99
  Then ask the project which of those files it has also touched:
98
100
 
99
101
  ```bash
@@ -155,7 +157,7 @@ pnpm typecheck && pnpm test && pnpm lint && pnpm build
155
157
 
156
158
  `pnpm install` can retain older transitive dependencies in `pnpm-lock.yaml` even after the template raises a direct dependency. Run `pnpm dedupe` to refresh compatible resolutions before synchronizing Skills from the final `node_modules`. Review and include the resulting lockfile changes in the upgrade. If type checking still reports incompatible types from two versions of the same package, follow [dependency resolution conflicts](references/edge-cases.md#dependency-resolution-conflicts) before changing application code.
157
159
 
158
- `typecheck` is doing real work here — it catches the broken import a removal left behind. Then run the application and check what the delta touched: sign-in, the user's pages, navigation, locale switching, any new migration. Passing commands are not evidence the application still behaves. For a theme or shell change, also complete the [theme upgrade checks](references/theme-upgrade.md); token changes alone do not verify the application-owned consumers.
160
+ `typecheck` is doing real work here — it catches the broken import a removal left behind. Before starting the application against retained data, complete the applicable [database upgrade checks](references/database-upgrades.md); startup may apply migrations automatically. Then run the application and check what the delta touched: sign-in, the user's pages, navigation, locale switching, any new migration. Passing commands are not evidence the application still behaves. For a theme or shell change, also complete the [theme upgrade checks](references/theme-upgrade.md); token changes alone do not verify the application-owned consumers.
159
161
 
160
162
  Report the range merged, how each contested file was decided, any manual actions and their validation, and how to roll back.
161
163
 
@@ -0,0 +1,64 @@
1
+ # Database upgrades
2
+
3
+ Use this procedure when a template or dependency upgrade changes migrations, or when an upgrade reports checksum drift. Read the target versions' changelogs and upgrade notes for the application and its registered plugins. The template source diff alone does not show plugin migrations. Match each instruction to the installed versions, configured dialect, connection, and execution history; do not replay every historical upgrade instruction.
4
+
5
+ ## Before applying migrations
6
+
7
+ Identify the database the target application will use and whether startup applies migrations or seeds automatically. Finish the applicable checks before starting it against retained data. A source branch, an older archive, or a successful build is not a database backup: have a restorable database backup and coordinate files or object storage when the upgrade affects their references. Record any irreversible migrations and whether the previous runtime can use the resulting schema.
8
+
9
+ Use the CLI from the target packages with the intended application's configuration and environment. In a source project, invoke `pnpm nocobase`; for a built application, use `node dist/cli/index.js` in its deployment context, preserving its config, environment, and storage paths. Do not run a development checkout against production as a shortcut. For an app-installer installation, retain the installer's lifecycle and configuration handling; if its supported workflow cannot perform a required release-specific preparation, establish that procedure before retrying the upgrade.
10
+
11
+ Preview pending work with the target CLI:
12
+
13
+ ```bash
14
+ pnpm nocobase db apply --dry-run --json
15
+ ```
16
+
17
+ The default connection is selected unless `--connection <name>` or `--all` is supplied. Keep preview, repair, and apply scoped to the same intended managed connections; plugins contribute to the default connection. An apply dry run discovers pending tasks by comparing their names with execution history. It does not check recorded checksums, even with `onChecksumMismatch: error`, and does not execute migration bodies or validate existing data against new constraints. A successful preview is therefore not evidence that checksums or data prerequisites are satisfied.
18
+
19
+ ## Review checksum drift
20
+
21
+ Before applying target migrations or starting the target application against retained data, inspect checksums independently with the target CLI, even when release notes mention no historical corrections and the apply preview succeeds:
22
+
23
+ ```bash
24
+ pnpm nocobase db repair --dry-run --json
25
+ ```
26
+
27
+ This preview is read-only and checks both executed migrations and seeds. If it proposes no checksum changes, skip the actual repair command and continue with the pending tasks and data prerequisites. Writing repaired checksums remains conditional on reviewing and authorizing the changes below.
28
+
29
+ Match every proposed change to its owning package, migration or seed name, and the documented source change. `db repair` updates all mismatching executed migration and seed checksums in the selected connections; it has no per-migration allowlist. An unexplained entry means investigate before repairing that connection, even when other entries are expected. Do not weaken the checksum policy, edit migration sources or history by hand, or use `db reset` or `db redo` to bypass the failure.
30
+
31
+ Before writing any repair, stop the application and other writers and take a restorable backup that includes the original migration and seed history. Keep that backup paired with the previous runtime. Once every proposed checksum change is explained and the operation is within the authorized upgrade scope, acknowledge it with the same target sources and connection selection:
32
+
33
+ ```bash
34
+ pnpm nocobase db repair --json
35
+ ```
36
+
37
+ The CLI confirms before writing; non-interactive execution requires `--force`. Use that flag only for the reviewed repair already authorized by the user. Repair changes recorded checksums only: it does not rerun migrations, change schema or business data, or make a failed migration count as successful. An upstream fix that changes an old schema still needs its forward migration after repair. This procedure does not authorize editing merged migrations yourself.
38
+
39
+ For an app-installer installation, do not run actual repair as preparation for a subsequent ordinary `upgrade`: the installer takes its SQLite backup after stopping the application, so that backup would already contain the repaired history. On failure it can restore checksums that the previous runtime rejects under `onChecksumMismatch: error`, even without a schema change. Establish a supported maintenance procedure that backs up before repair and restores that same backup before starting the old runtime on failure. Merely keeping an extra pre-repair backup does not make the installer's automatic rollback select it. If the selected installer cannot coordinate these steps, complete only the read-only checks until that procedure is available.
40
+
41
+ ## Apply and verify
42
+
43
+ For a source application, after completing the independent checksum check, any required repair, and the documented data preparation, review the pending tasks again with the apply preview and execute `pnpm nocobase db apply --json` within the authorized upgrade scope. For a deployment, keep backup, repair, migration, and recovery inside the established maintenance procedure; use the ordinary installer upgrade directly when no repair is needed. Check the command result and relevant application behavior, including reads and writes affected by the migration; a running process alone is insufficient. Keep the reviewed checksum changes, migration results, and recovery path in the upgrade report.
44
+
45
+ If a migration rejects existing data, preserve it and resolve the reported records under a data migration plan before retrying. For example, shortening a stored archive key without moving the corresponding archive breaks downloads. Do not silently truncate data to make a constraint pass.
46
+
47
+ MySQL DDL can leave partial tables or indexes after a failed migration without a successful history entry. Checksum repair cannot reconcile those objects. Preserve a database containing application data and diagnose the partial schema before retrying. A new empty database is appropriate only when the failed installation is confirmed disposable; never infer that from a missing history entry.
48
+
49
+ ## Recovery after a schema change
50
+
51
+ A code rollback does not run migration `down()` methods. If the applied correction is irreversible and the old runtime requires the old schema, restore a compatible backup together with the matching runtime, configuration, and file storage. Account for writes since the backup. Do not promise that `db rollback` or `db redo` can reverse an irreversible migration.
52
+
53
+ app-installer can restore the SQLite databases it backed up. It does not back up or restore external MySQL, PostgreSQL, or SQL Server databases; `--backup-done` acknowledges an operator backup, not automatic restoration. An exit reporting that the previous release is running does not prove an external database was restored. Use `--no-restore` only when retaining the upgraded schema is an intentional, verified compatible choice.
54
+
55
+ ## Known correction: agents and releases MySQL indexes
56
+
57
+ When the installed plugins cross the index correction described in the [agents upgrade notes](https://github.com/nocobase/nocobase/blob/943a9a8a80cc1f76c7a01ecd4965a2a0c51be1eb/packages/plugins/app-plugin-agents/docs/mysql-installation-upgrade.md) or [releases upgrade notes](https://github.com/nocobase/nocobase/blob/943a9a8a80cc1f76c7a01ecd4965a2a0c51be1eb/packages/plugins/app-plugin-releases/docs/mysql-installation-upgrade.md), check these task identities against the target sources and database history:
58
+
59
+ | Registered plugin | Corrected creation migration | Forward correction |
60
+ | ------------------------------- | -------------------------------- | -------------------------------------- |
61
+ | `@nocobase/app-plugin-agents` | `202610020003_ag_create_runs` | `202610260001_ag_drop_directory_index` |
62
+ | `@nocobase/app-plugin-releases` | `202610020001_rel_create_tables` | `202610260002_rel_bound_artifact_keys` |
63
+
64
+ The documented checksum changes apply to installations that executed the old creation sources on any supported dialect, not only MySQL. Only installed plugins are relevant. New databases that run the corrected sources need no checksum acknowledgment; their forward corrections may skip without a history entry. Existing old schemas require the forward corrections, which are irreversible when applied. The releases correction rejects archive keys longer than 172 characters before changing the schema; follow the release notes for data handling rather than rewriting keys independently of stored archives. Treat any other checksum difference as separate evidence to investigate.
@@ -98,11 +98,11 @@ Apply the agreed outcome to the manifest and composition roots together, then ve
98
98
 
99
99
  ## Migrations
100
100
 
101
- A release can ship a migration under `database/`. Copy it in like any added file, then `pnpm nocobase db apply`.
101
+ A release can ship a migration under `database/`, and updated plugins can supply migrations without any application file changing. Copy new application migrations in like other added files, then follow [database upgrades](database-upgrades.md) before applying them or starting the application against retained data.
102
102
 
103
103
  Never edit a migration that arrives this way, and never edit one already run — a correction goes in a new migration. The user's own migrations and seeds stay byte for byte where they are; an upgrade never rewrites them.
104
104
 
105
- Template cleanup does not authorize deleting previously executed application migrations or seeds, even when they originally came from the template. Preserve their original package owner, paths, contents, and history; do not reset checksums, drop tables, or repoint history to another template. For directory or connection changes, follow [existing application migration rules](../../nocobase-app-development/references/migrations.md#existing-applications) and verify the original sources remain available in the deployment.
105
+ Template cleanup does not authorize deleting previously executed application migrations or seeds, even when they originally came from the template. Preserve their original package owner, paths, contents, and history; do not reset checksums to hide unexplained drift, drop tables, or repoint history to another template. A documented upstream correction requires the separate checksum review in [database upgrades](database-upgrades.md#review-checksum-drift). For directory or connection changes, follow [existing application migration rules](../../nocobase-app-development/references/migrations.md#existing-applications) and verify the original sources remain available in the deployment.
106
106
 
107
107
  Unregistering a plugin leaves its records and migration history intact. Do not roll back a retired plugin's migrations after removing its sources; an intentional rollback requires restoring the original plugin version first.
108
108
 
@@ -62,6 +62,8 @@ A deployment package carries code and production dependencies, not business data
62
62
 
63
63
  Before an update that can change schema, take a database and file backup and confirm the restore path. Ensure the database account can perform the configured migration and seed operations. Do not point a new instance at an empty database and describe the result as a data migration.
64
64
 
65
+ Read [database upgrades](../nocobase-app-upgrade/references/database-upgrades.md) when the update changes migrations or reports checksum drift, before starting the new runtime. It covers target-version upgrade notes, reviewed checksum repair, data prerequisites, and irreversible changes, including plugin migrations that the application's source diff does not show. `db repair` acknowledges source checksums only; it does not upgrade schema or recover a partially failed installation.
66
+
65
67
  The default configuration uses managed schema migrations and automatic seeds. Determine whether the deployment should run them on startup. If migrations or seeds are run separately, set the corresponding automatic options to `false` and execute the supported CLI operation before starting the application. Record the migration and seed result; a successful process start alone is insufficient.
66
68
 
67
69
  ## Build and review production configuration