Skip to content

Develop a business feature ​

Using an order list or equipment booking as an example, start by reading each repository’s AGENTS.md, README.md, and docs/kaiwu-project-blueprint.json. Use JDK 21 for the backend and the pnpm version pinned in package.json for the frontend.

AreaResponsibility & conventions
Backend api moduleDefine query and write DTOs plus paginated responses. Carry long business IDs as strings in the frontend and JSON.
domain moduleImplement entities, mappers, services, and controllers. Bound page sizes and enforce @RequirePermission.
boot, DB & sql/schema.sqlAppend the next Flyway migration in the business backend and update sql/schema.sql. The platform DB is separate.
Platform manifests kaiwu/*.ymlDual-repo scaffolds store manifests under backend kaiwu/; product-led projects (project adopt) maintain them under frontend kaiwu/ (referenced by the backend via kaiwu/frontend-manifests). Permission codes (e.g., order:order:list) must match across UI, menus.yml, and backend @RequirePermission.
Frontend layer @/kaiwu & UIPages import rootContainer, useCan / <Can>, useDict, useProjectConfig, kaiwuRequest, and useKaiwuSession from @/kaiwu. You can swap out the UI component library while keeping src/kaiwu/ intact. Store stable status values and resolve labels via managed dictionaries.
Rules, scenarios & contractRegister new module permissionPrefix entries in docs/kaiwu-project-blueprint.json; link rule IDs across docs/business-rules.md, mock-support/, docs/acceptance-scenarios.md, and tests/scenarios.test.mjs.

Verify the feature ​

Product mock stage (runs standalone in the frontend repository):

bash
pnpm verify:mock
pnpm test:scenarios
pnpm test:browser

Real backend integration (pass KAIWU_SERVICE_DIR / KAIWU_FRONTEND_DIR when repos are not siblings, and pass whichever repo owns kaiwu/*.yml to project sync):

bash
(cd ../business/order-center-service && bash scripts/verify.sh)
(cd ../business/order-center-web && corepack pnpm install --frozen-lockfile && KAIWU_SERVICE_DIR=../business/order-center-service corepack pnpm verify)
./kaiwu project sync ../business/order-center-service
  • Grant permissions in the project permission center (or inspect initial roles.yml imported by project adopt), run pnpm dev:real, and open the app through the same-origin workbench.
  • Test both authorized and unauthorized users (and separate owners for row-scoped records), including direct API calls.
  • Before release, pnpm build runs check-dist.mjs to block mock markers from dist/, and sh scripts/check-runtime-image.sh "$IMAGE" <code> verifies the production container serves the built index and returns 404 for /__mock/. Roles and row filtering

Hand off a working frontend ​

Whether starting from kaiwu-web-starter or the project factory, product and engineering work in the same frontend repository—eliminating static wireframes and duplicate frontend rewrites:

  1. Product & AI build on product. Build working screens, src/services/ TypeScript contracts, and mock-support/ handlers; run pnpm dev and use /__mock/ to test across personas. Record numbered rules in docs/business-rules.md and happy, error, and unauthorized cases in docs/acceptance-scenarios.md.
  2. Handoff via handoff/<batch> MR. Once pnpm verify:mock, pnpm test:scenarios, and pnpm test:browser pass, cut a snapshot branch handoff/<batch> and open an MR to dev using .gitlab/merge_request_templates/Product-Handoff.md, freeing product for the next batch.
  3. Adopt & implement the backend. If not yet registered, run ./kaiwu project adopt <frontend-dir> --apply to register the frontend, sync initial manifests/roles, and generate the companion Spring Boot repo; implement APIs, @RequirePermission, concurrency control, and data scopes.
  4. Wire pnpm dev:real and ship. Keep approved UX and layouts intact while aligning payloads, error messages, and loading/empty states. Re-verify with pnpm verify and pnpm dev:real, promote to main, and merge release fixes back into product.

Apache License 2.0