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.
| Area | Responsibility & conventions |
|---|---|
Backend api module | Define query and write DTOs plus paginated responses. Carry long business IDs as strings in the frontend and JSON. |
domain module | Implement entities, mappers, services, and controllers. Bound page sizes and enforce @RequirePermission. |
boot, DB & sql/schema.sql | Append the next Flyway migration in the business backend and update sql/schema.sql. The platform DB is separate. |
Platform manifests kaiwu/*.yml | Dual-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 & UI | Pages 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 & contract | Register 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:browserReal 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.ymlimported byproject adopt), runpnpm 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 buildrunscheck-dist.mjsto block mock markers fromdist/, andsh 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:
- Product & AI build on
product. Build working screens,src/services/TypeScript contracts, andmock-support/handlers; runpnpm devand use/__mock/to test across personas. Record numbered rules indocs/business-rules.mdand happy, error, and unauthorized cases indocs/acceptance-scenarios.md. - Handoff via
handoff/<batch>MR. Oncepnpm verify:mock,pnpm test:scenarios, andpnpm test:browserpass, cut a snapshot branchhandoff/<batch>and open an MR todevusing.gitlab/merge_request_templates/Product-Handoff.md, freeingproductfor the next batch. - Adopt & implement the backend. If not yet registered, run
./kaiwu project adopt <frontend-dir> --applyto register the frontend, sync initial manifests/roles, and generate the companion Spring Boot repo; implement APIs,@RequirePermission, concurrency control, and data scopes. - Wire
pnpm dev:realand ship. Keep approved UX and layouts intact while aligning payloads, error messages, and loading/empty states. Re-verify withpnpm verifyandpnpm dev:real, promote tomain, and merge release fixes back intoproduct.