交给 AI 编码工具
产品和开发都可以通过一句话启动 AI 工具:产品在独立前端仓用内置 Mock 做出可点击页面,开发接手同一套前端与规则契约,纳管并补齐 Spring Boot 后端。
产品先做演示:无平台一句话起步
如果只需在本机做出可交互、可切角色的前端演示(无需安装 Kaiwu 平台、Docker、JDK 或 MySQL),确保本机已有 Git、Node 22 和 pnpm 10,在空目录直接把下面这句话交给 AI 编码工具(起步仓开源地址:kaiwu-web-starter):
text
从 https://github.com/kaiwuzaidao/kaiwu-web-starter 获取 Kaiwu 前端起步仓最新稳定版(如 v0.3.0),按仓库内 AGENTS.md 初始化我的业务前端项目,帮我做一个设备预约前端:让员工能看到会议室投影仪的空闲时段,选时间预约或取消自己的预约,两个人选到同一时段时让后提交的人看得懂出了什么问题。用内置 Mock 跑起来给我本地可点的地址。AI 会克隆起步仓并按仓库内的 AGENTS.md 自动执行初始化(新建空白项目或用 --example booking 启动双人预约示例),完成页面、src/services/ 类型、mock-support/ 处理器、规则与场景文档后运行 pnpm dev,并交付本地 /__mock/ 角色切换地址。产品在 product 分支验收后,由 AI 切出 handoff/<批次> 分支并按交接模板向 dev 发起 MR。
从空目录启动平台并建双仓
如果需要同时启动完整 Kaiwu 平台(或直接由平台创建双仓),在空目录中把这句话复制给能使用本机终端的 AI 编码工具:
text
从 https://github.com/kaiwuzaidao/kaiwu 获取 Kaiwu 最新稳定版,按 AGENTS.md 在本机启动。问我想开发什么项目,再按我的回答准备前后端。在已有项目中开发功能
在 AI 编码工具中打开业务项目的前后端仓库(或已验收的产品前端仓),然后告诉它:
text
读当前项目的 AGENTS.md,问我想做哪个功能,再按我的需求开发和测试。安装步骤见安装与首次登录,从起步仓起步或平台建项见生成并运行业务项目。AI 也可以读取文档索引或完整手册。
接手前对齐三项约束
| 关注点 | 在哪里改、如何校验 |
|---|---|
| 接入层与 UI 解耦 | 业务页面统一从 @/kaiwu 导入 rootContainer、useCan、<Can>、useDict、useProjectConfig、kaiwuRequest 与 useKaiwuSession,业务 API 放在 src/services/。可自由替换 UI 组件库,但不得绕过接入层或改动 src/kaiwu/ 校验基线。 |
| 三端权限与清单归属 | 新模块前缀登记在 docs/kaiwu-project-blueprint.json。产品主导项目将 menus.yml、dicts.yml、configs.yml、roles.yml 等维护在前端仓 kaiwu/;页面权限、菜单 BUTTON 与后端 @RequirePermission 三端同码。 |
| 规则、场景与 Mock 双向绑定 | 业务规则以编号写在 docs/business-rules.md(如 EQ-01),验收步骤写在 docs/acceptance-scenarios.md(如 S01)。mock-support/ 引用规则编号,tests/scenarios.test.mjs 对应场景编号;mock/ 只保留 index.ts 并以 501 兜底收尾。 |
同一条规则,Mock 与真实服务各验一遍
以设备预约为例,假设产品确认:EQ-01 同设备有效预约按半开区间 [开始, 结束) 判重叠(冲突返回 409);EQ-02 员工只能查看或取消自己的预约(越权读改返回 404);EQ-03 取消后立即释放时段。产品与开发沿同一张表验收:
| 场景 | 产品用 Mock 点验(pnpm dev) | 开发接真实服务复验(pnpm dev:real) |
|---|---|---|
S01 首次预约(EQ-01) | 员工甲在 /__mock/ 登录后预约 10:00–11:00,在「我的预约」中可见。 | 经 Gateway 创建后重新读取,业务库存在一条归甲的有效记录。 |
S02 首尾相接(EQ-01) | 预置甲 10:00–11:00;乙可订 11:00–12:00,提交零时长时被拒绝。 | 相邻预约有效,零时长请求被服务端拒绝且记录数不变。 |
S03 并发争用(EQ-01) | 甲乙看到同一空档,甲提交后乙提交重叠时段收到冲突提示。 | 两个独立登录会话与事务在服务端同时提交重叠时段,恰好一次成功、一次 409。 |
S04 越权访问(EQ-02) | 乙只见忙闲状态,看不到甲的预约明细与取消按钮。 | 有相同功能权限的乙直接请求甲的预约明细或取消接口均返回 404,响应不含甲的信息。 |
S05 取消释放(EQ-02、EQ-03) | 甲取消后,乙刷新空档即可重新预约。 | 甲的记录变为已取消,乙的预约持久化生效。 |
做到哪里算完成
- 产品 Mock 阶段:在业务前端仓通过
pnpm verify:mock、pnpm test:scenarios与pnpm test:browser,交付验收提交 SHA、演示角色、已确认规则编号及未决事项。 - 纳管与清单同步:在入口仓执行
./kaiwu project adopt <前端仓>预览,确认后加--apply登记前端、导入清单与首次角色并取回配套后端(可选 Workflow 项目可运行./kaiwu workflow sync <前端仓>)。日常清单变更用./kaiwu project sync <清单仓>预览后再--apply。 - 真实联调与三端门禁:实现后端接口、数据范围与并发控制后,并行检出或通过
KAIWU_SERVICE_DIR/KAIWU_FRONTEND_DIR执行两端校验(后端bash scripts/verify.sh,前端pnpm verify)。使用pnpm dev:real从工作台同源入口复验所有场景,并保留状态码与数据库断言结果。 - 生产隔离与镜像校验:前端
pnpm build自动运行check-dist.mjs拦截模拟标识;容器构建后运行sh scripts/check-runtime-image.sh "$IMAGE" <项目编码>,确认首页正常返回且/__mock/返回 404。 - 交接操作状态:在 MR 或交接单写明项目编码、分支或提交 SHA、规则与场景编号、验证环境与命令结果,以及尚未验证的条件。远程设备授权由账号持有人确认;凭据由操作者在本机终端查看。
平台内置助手的模型、能读取的数据和可执行操作是另一条接入路径,见项目助手。