Skip to content

开发第一个业务功能 ​

以「订单列表」或「设备预约」为例。先读业务仓的 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 起步还是从项目工厂取回前端仓,产品与开发都在同一个前端仓里协作,不再重复“画原型 → 前端重写 → 联调扯皮”:

  1. 产品经理和 AI 在 product 分支做正式页面。 在生成好的 React 仓(默认 Ant Design 或自选 UI 库)编写页面、src/services/ 类型与 mock-support/ 处理器,使用 pnpm dev 打开 /__mock/ 切换演示身份试用。同时在 docs/business-rules.md 与 docs/acceptance-scenarios.md 固化规则编号和正常、异常、无权三类场景。
  2. 通过快照分支与交接 MR 交给开发。 在 pnpm verify:mock、pnpm test:scenarios 与 pnpm test:browser 全绿后,从已验收提交切出 handoff/<批次> 分支,按 .gitlab/merge_request_templates/Product-Handoff.md 向 dev 发起合并请求;产品可继续在 product 迭代下一批。
  3. 开发纳管并补齐后端服务。 若尚未登记项目,运行 ./kaiwu project adopt <前端仓> --apply 登记前端、导入清单与首次角色并取回配套 Spring Boot 仓;在后端实现业务 API、@RequirePermission 与并发/数据范围控制。
  4. 在同一前端运行 pnpm dev:real 联调上线。 后端工程师保留已验收交互与布局,仅作字段对齐、错误提示与加载空态等微调,并同步更新契约与测试;运行 pnpm verify 与同源复验后合入 main 发布,发布修复按约定回流 product。

Apache License 2.0