开发第一个业务功能
以「订单列表」或「设备预约」为例。先读业务仓的 AGENTS.md、README.md 与 docs/kaiwu-project-blueprint.json。后端使用 JDK 21,前端按 package.json 固定版本的 pnpm 安装依赖。平台底座交付工程骨架与平台能力,具体业务表、接口和页面在业务仓实现。
| 改动位置 | 职责与规范 |
|---|---|
后端 api 模块 | 定义查询请求与分页响应。长整型业务 ID 在前端与 JSON 中按字符串传递。 |
domain 模块 | 实现实体、Mapper、服务与 Controller,限制分页上限,接口加上 @RequirePermission。 |
boot、业务库和 sql/schema.sql | 在业务仓 Flyway 目录追加下一号迁移并更新快照。平台库独立维护。 |
平台清单 kaiwu/*.yml | 传统双仓默认维护在后端 kaiwu/;产品主导项目(project adopt)维护在前端 kaiwu/(后端以 kaiwu/frontend-manifests 定位)。权限码(如 order:order:list)与后端注解、前端校验保持三端同码。 |
前端接入层 @/kaiwu 与页面 | 页面通过 @/kaiwu 使用 rootContainer、useCan / <Can>、useDict、useProjectConfig、kaiwuRequest 与 useKaiwuSession,UI 组件库可整体替换(默认提供 Ant Design 皮肤适配器)。业务状态以稳定值入库,标签走受管字典。 |
| 规则、场景与模块契约 | 新增模块的 permissionPrefix 登记到 docs/kaiwu-project-blueprint.json;业务规则编号写在 docs/business-rules.md,验收步骤写在 docs/acceptance-scenarios.md 并与 mock-support/、tests/scenarios.test.mjs 双向绑定。 |
如何验收
产品 Mock 阶段(不依赖后端,可在前端仓独立运行):
bash
pnpm verify:mock
pnpm test:scenarios
pnpm test:browser前后端真实联调(两仓非平级默认位置时,前端用 KAIWU_SERVICE_DIR、后端用 KAIWU_FRONTEND_DIR 指定路径;清单位于后端还是前端则传对应仓路径):
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- 在「权限中心」为测试角色授予权限(或核对
project adopt首次导入的roles.yml),在前端运行pnpm dev:real并从同源工作台进入验证。 - 准备两类用户:有权限者应能完成查询/提交;无该权限者(或跨归属用户)即使直接调 API 也必须被服务端拒绝。
- 交付镜像前,前端
pnpm build自动运行check-dist.mjs核对无模拟标记;镜像构建后可执行sh scripts/check-runtime-image.sh "$IMAGE" <项目编码>验证首页与/__mock/返回 404。角色与行级数据
用同一套前端完成产品交接
无论从 kaiwu-web-starter 起步还是从项目工厂取回前端仓,产品与开发都在同一个前端仓里协作,不再重复“画原型 → 前端重写 → 联调扯皮”:
- 产品经理和 AI 在
product分支做正式页面。 在生成好的 React 仓(默认 Ant Design 或自选 UI 库)编写页面、src/services/类型与mock-support/处理器,使用pnpm dev打开/__mock/切换演示身份试用。同时在docs/business-rules.md与docs/acceptance-scenarios.md固化规则编号和正常、异常、无权三类场景。 - 通过快照分支与交接 MR 交给开发。 在
pnpm verify:mock、pnpm test:scenarios与pnpm test:browser全绿后,从已验收提交切出handoff/<批次>分支,按.gitlab/merge_request_templates/Product-Handoff.md向dev发起合并请求;产品可继续在product迭代下一批。 - 开发纳管并补齐后端服务。 若尚未登记项目,运行
./kaiwu project adopt <前端仓> --apply登记前端、导入清单与首次角色并取回配套 Spring Boot 仓;在后端实现业务 API、@RequirePermission与并发/数据范围控制。 - 在同一前端运行
pnpm dev:real联调上线。 后端工程师保留已验收交互与布局,仅作字段对齐、错误提示与加载空态等微调,并同步更新契约与测试;运行pnpm verify与同源复验后合入main发布,发布修复按约定回流product。