Skip to content

Sync manifests and transfer configuration ​

Manifest ownership follows how the project starts: dual-repo scaffolds (project new) store kaiwu/*.yml in the backend repository; product-led projects (started from kaiwu-web-starter and adopted via project adopt) maintain kaiwu/*.yml in the frontend repository so the mock runtime reads them directly and the backend points to them via kaiwu/frontend-manifests.

Add this list item to your project’s kaiwu/dicts.yml, replacing order-center with your project code. If the file still contains the initial empty list [], replace it with the example. Store the stable value PENDING in the application and resolve its label through the dictionary (e.g., via useDict from @/kaiwu).

yaml
- dictCode: order-center.order_status
  name: Order status
  items:
    - value: PENDING
      label: Pending
      color: processing
      default: true

Run the first command in the entry repository to preview the entire plan. Check the environment, project, and every resource before applying it. For product-led projects, pass the frontend directory instead (project adopt imports roles.yml on initial adoption, while subsequent project sync runs preserve platform role edits unless --with-access is explicitly supplied):

bash
./kaiwu project sync ../business/order-center-service
./kaiwu project sync ../business/order-center-service --apply
File under kaiwu/Purpose
menus.yml, dicts.yml, configs.ymlMenus and buttons, dictionaries, and managed settings. Supply defaults in consuming code.
jobs.yml, i18n.ymlScheduled task declarations and project translations.
data-scopes.yml, roles.ymlScope resources and role grants. Initial adoption imports roles.yml once; ongoing role updates require explicit --with-access.
workflows/ (optional)Workflow definitions and bindings for projects using the optional Workflow service (./kaiwu workflow sync <frontend-dir>).

Inspect the stable value in the project dictionary and verify the page in another language. Sync creates resources, updates fields owned by the manifest and preserves existing setting values. Kaiwu uses project-scoped referenced i18n (scope_id isolates each project from the global catalog), so project admins can manage their own translations without global i18n permissions and without leaking vocabulary across projects. The plan lists removed declarations; confirm any deletions individually on the configuration transfer page. Global defaults and the built-in system project belong to the platform. Managed settings · Sync rules

Global dictionary showing data scope types and stable values

Transfer between environments ​

Promoting menus, dictionaries, role grants, and scheduled jobs from staging to production often relies on fragile SQL scripts or manual re-entry—leading to mismatched database IDs, missing row scopes, or test jobs firing immediately in production.

Export a package in the source project’s Permission Center → Config Handover and import it into the matching project in the target environment with four built-in safeguards:

  • Six-file full snapshot: The JSON handover package bundles dicts.yml, configs.yml, menus.yml, roles.yml (including role dataScopes), jobs.yml, and i18n.yml in the exact same YAML format as kaiwu/ plus a sha256 digest. Secret configs are automatically omitted with explicit warnings, and exported YAML files can be committed straight back into Git.
  • Business-key matching, zero DB ID coupling: Menus match by permission code, route, or directory path, and custom-department data scopes match by deptCode rather than environment-specific primary keys.
  • Three-way baseline diff + 409 concurrency guard: plan compares the previous handover baseline, the incoming package, and the live target state to produce a plan hash; apply rejects with 409 if the target changed after preview.
  • Risk-tiered opt-in: Normal settings apply while preserving live runtime values; role grants (ACCESS) are off by default and opt in as a group; source removals (REMOVED_AT_SOURCE) require individual selection, while target-only additions are flagged as drift and never auto-deleted. New scheduled jobs import as disabled and validate online handlers; members and secrets stay local to each environment, with every transfer recorded in handover audit history. Package contents

Order Center configuration transfer and history

Apache License 2.0