# 快速开始:安装与首次登录
::: tip 产品先做演示?无需安装 Docker 与平台
如果只需在本地做出可点击、可切角色的产品前端(Mock 运行时),只需要 **Git、Node 22 和 pnpm 10**。直接克隆 `kaiwu-web-starter` 起步,见[产品先做前端与纳管](https://kaiwu.shengzhiweilai.online/after-generation#product-first)和[无平台一句话起步](https://kaiwu.shengzhiweilai.online/ai-development#product-prompt-section)。需要完整平台与后端联调时,继续按下方启动 Kaiwu。
:::
::: tip 推荐使用 AI 编码工具自动完成
如果你正在使用 Claude Code、Codex、Cursor 等支持本地终端的 AI 工具,可以直接[复制 AI 开工提示词](https://kaiwu.shengzhiweilai.online/ai-development),让它自动检查环境、启动平台并引导你建仓。
:::
## 1. 准备环境
本机需要安装:**Git**、**Docker(含 Compose v2)**、**OpenSSL** 和 **curl**。
## 2. 克隆并启动平台(以 v0.3.0 为例)
```bash
git clone --branch v0.3.0 --depth 1 https://github.com/kaiwuzaidao/kaiwu.git
cd kaiwu
./kaiwu doctor
KAIWU_DB_TYPE=mysql ./kaiwu up
```
> 使用 Gitee 可将仓库地址替换为 `https://gitee.com/wujm12138/kaiwu.git`。`./kaiwu up` 会自动拉取运行仓、初始化本地 MySQL、执行迁移并启动平台。
常见环境补充说明(Colima / 源码构建 / 已有数据库)
- **macOS Colima 用户**:请将代码克隆在虚拟机可共享挂载的目录下(如 `$HOME` 子目录)。
- **镜像与源码构建**:发行版默认从 GHCR 拉取 `amd64 / arm64` 镜像,拉取失败会自动回退到源码构建;也可追加 `--build` 强制从源码构建。
- **已有 MySQL 或达梦 DM8**:如需连接外部数据库或启动第二套实例,见[数据库与部署排错](https://kaiwu.shengzhiweilai.online/operations)。
## 3. 登录与验证
启动完成后,浏览器打开 ****:
1. 使用默认账号 `admin` 和终端打印的随机初始密码登录(首次登录按提示修改密码)。
2. 如果忘记初始密码,可在 `kaiwu` 目录执行 `./kaiwu credentials` 重新查看(改密后请使用新密码)。
3. 进入工作台后,可用以下命令快速核对服务健康状态:
```bash
./kaiwu status
curl -fsS http://127.0.0.1:8088/actuator/health
```
停止平台执行 `./kaiwu down`;下次在同一目录运行 `./kaiwu up` 会自动复用已有数据卷。

## 下一步
- [生成并运行第一个业务项目 →](https://kaiwu.shengzhiweilai.online/after-generation)
- [10 分钟看懂 Kaiwu 运作机制 →](https://kaiwu.shengzhiweilai.online/how-it-works)
- [部署与排错指南 →](https://kaiwu.shengzhiweilai.online/operations) · [发行版快速开始][quickstart]
# 生成并运行业务项目
Kaiwu 支持两种起步方式:**方式一**由产品先在独立前端仓做出可交互 Mock 再纳管生成配套后端;**方式二**在平台已启动时直接通过项目工厂生成前后端双仓。下文分别用设备预约(`equipment-booking`)和订单中心(`order-center`)举例,运行时请换成你自己的项目名称和编码。
## 方式一:产品先做前端,再纳管生成后端 {#product-first}
在 `kaiwu-web-starter` 根目录运行以下命令(需要 Git、Node 22、pnpm 10,无需先启动 Kaiwu 平台)。默认初始化空白项目;若要体验内置的双人设备预约演示,在首条命令末尾加上 `--example booking`:
```bash
node scripts/kaiwu-init.mjs --code equipment-booking --name 设备预约
cd ../equipment-booking-web
pnpm install --frozen-lockfile
pnpm dev
```
打开终端打印的本地地址并访问 `/__mock/` 选择演示身份,验证页面、规则与场景。产品在 `product` 分支验收并提交交接 MR 后,开发在已登录平台的入口仓执行纳管:
```bash
./kaiwu login --client "project-development"
./kaiwu project adopt ../equipment-booking-web
./kaiwu project adopt ../equipment-booking-web --apply
```
- 不带 `--apply` 只预览将登记的项目、前端清单与首次导入的角色,零写入;加上 `--apply` 后自动建项、同步清单与 `roles.yml`,并在同级目录生成配套后端 `../equipment-booking-service`(在网页「项目工厂」显示为 `ADOPT_FRONTEND` /「沿用已有前端」)。
- 日常清单变更使用 `./kaiwu project sync ../equipment-booking-web`(保留平台人工调整过的角色,除非显式加 `--with-access`);单独启用 Workflow 服务的项目还可用 `./kaiwu workflow sync ../equipment-booking-web` 预览流程导入。[前端纳管决策][adopt]
## 方式二:在平台直接开通并生成双仓
前置条件是平台可登录,操作账号有开通项目的权限。在网页选「项目管理 → 开通项目」,填写名称和编码;在「项目工厂」等待成功后,可分别下载前后端 ZIP。也可在入口仓目录用 CLI 操作:
```bash
./kaiwu login --client "project-development"
./kaiwu whoami
./kaiwu project new order-center --name "Order Center" --package com.example.ordercenter
./kaiwu project status order-center --wait
./kaiwu project pull order-center
./kaiwu project-up ../business/order-center-service ../business/order-center-web
```
登录时在浏览器核对客户端名称并确认设备授权。本机初始账号也支持 `login --local`;本人已改密或免点击授权失败时,按终端给出的设备链接操作。若 `order-center` 已生成,从查询状态继续。每个编码成功生成一次,下载制品可重复取用。

v0.2.0 已知问题:取回的项目可能缺少打包资源,或因前端配置文件权限而反复重启。即使启动命令返回成功,也请从工作台打开业务页并验证一次请求。排查时查看业务容器的状态和日志。[启动修复进展](https://github.com/kaiwuzaidao/kaiwu-system-service/pull/1)
## 交付检查
- `../business/order-center-service/pom.xml` 和 `../business/order-center-web/package.json`(或纳管后的 `../equipment-booking-service` 与 `../equipment-booking-web`)分别位于独立 Git 仓。
- `project-up` 构建两个服务、接入本机路由。回工作台点击项目,从 `/apps/<项目编码>/` 打开;业务 API 经 `/<项目编码>-api/`。
- 只有项目成员看得到相应入口。无法进入时,先核对入口地址、成员状态和角色,再看 Gateway 日志。
- 用 `./kaiwu project-down <项目编码>` 停止这个业务栈。业务源码在两个仓库中继续维护。
[开发第一个业务功能](https://kaiwu.shengzhiweilai.online/business) · [项目工厂契约][factory]
## 开发时打开前端
无论是起步仓初始化还是项目工厂生成的前端,均内置两套本地启动模式:
- **本地 Mock 演示(`pnpm dev`)**:默认启用 Umi 内置 Mock 运行时,打开 `/__mock/` 切换演示角色、执行内存 CRUD 与重置数据;未注册路径返回 501,Mock 代码不会打入生产构建产物。
- **真实网关联调(`pnpm dev:real`)**:同时将 `/api`、`/{code}-api` 与 `/{code}-svc` 转发给 Gateway(默认 `http://127.0.0.1:8088`,可用 `KAIWU_GATEWAY` 覆盖)。使用真实 `projectId`,优先从同源平台工作台进入以经由会话桥传递短期令牌;独立调试时可在启动前引导内存令牌。两个业务仓各自管理分支、评审和发布。
# 开发第一个业务功能
以「订单列表」或「设备预约」为例。先读业务仓的 `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` / ``、`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。[角色与行级数据](https://kaiwu.shengzhiweilai.online/access)
## 用同一套前端完成产品交接 {#product-handoff}
无论从 `kaiwu-web-starter` 起步还是从[项目工厂](https://kaiwu.shengzhiweilai.online/after-generation)取回前端仓,产品与开发都在同一个前端仓里协作,不再重复“画原型 → 前端重写 → 联调扯皮”:
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`。
# 交给 AI 编码工具
产品和开发都可以通过一句话启动 AI 工具:产品在独立前端仓用内置 Mock 做出可点击页面,开发接手同一套前端与规则契约,纳管并补齐 Spring Boot 后端。
## 产品先做演示:无平台一句话起步 {#product-prompt-section}
如果只需在本机做出可交互、可切角色的前端演示(无需安装 Kaiwu 平台、Docker、JDK 或 MySQL),确保本机已有 Git、Node 22 和 pnpm 10,在空目录直接把下面这句话交给 AI 编码工具(起步仓开源地址:[`kaiwu-web-starter`](https://github.com/kaiwuzaidao/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,问我想做哪个功能,再按我的需求开发和测试。
```
安装步骤见[安装与首次登录](https://kaiwu.shengzhiweilai.online/start),从起步仓起步或平台建项见[生成并运行业务项目](https://kaiwu.shengzhiweilai.online/after-generation)。AI 也可以读取[文档索引](https://kaiwu.shengzhiweilai.online/llms.txt)或[完整手册](https://kaiwu.shengzhiweilai.online/llms-full.txt)。
## 接手前对齐三项约束
| 关注点 | 在哪里改、如何校验 |
| --- | --- |
| **接入层与 UI 解耦** | 业务页面统一从 `@/kaiwu` 导入 `rootContainer`、`useCan`、``、`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`) | 甲取消后,乙刷新空档即可重新预约。 | 甲的记录变为已取消,乙的预约持久化生效。 |
## 做到哪里算完成
1. **产品 Mock 阶段**:在业务前端仓通过 `pnpm verify:mock`、`pnpm test:scenarios` 与 `pnpm test:browser`,交付验收提交 SHA、演示角色、已确认规则编号及未决事项。
2. **纳管与清单同步**:在入口仓执行 `./kaiwu project adopt <前端仓>` 预览,确认后加 `--apply` 登记前端、导入清单与首次角色并取回配套后端(可选 Workflow 项目可运行 `./kaiwu workflow sync <前端仓>`)。日常清单变更用 `./kaiwu project sync <清单仓>` 预览后再 `--apply`。
3. **真实联调与三端门禁**:实现后端接口、数据范围与并发控制后,并行检出或通过 `KAIWU_SERVICE_DIR` / `KAIWU_FRONTEND_DIR` 执行两端校验(后端 `bash scripts/verify.sh`,前端 `pnpm verify`)。使用 `pnpm dev:real` 从工作台同源入口复验所有场景,并保留状态码与数据库断言结果。
4. **生产隔离与镜像校验**:前端 `pnpm build` 自动运行 `check-dist.mjs` 拦截模拟标识;容器构建后运行 `sh scripts/check-runtime-image.sh "$IMAGE" <项目编码>`,确认首页正常返回且 `/__mock/` 返回 404。
5. **交接操作状态**:在 MR 或交接单写明项目编码、分支或提交 SHA、规则与场景编号、验证环境与命令结果,以及尚未验证的条件。远程设备授权由账号持有人确认;凭据由操作者在本机终端查看。
平台内置助手的模型、能读取的数据和可执行操作是另一条接入路径,见[项目助手](https://kaiwu.shengzhiweilai.online/assistant)。
# 成员、角色与数据范围
项目成员决定谁能进入项目,角色权限码决定能执行哪些操作,数据范围决定这些操作能访问哪些记录。下面以 `order-center` 为例,命令在入口仓执行。
```bash
./kaiwu whoami
./kaiwu access permissions order-center
./kaiwu access roles order-center
./kaiwu access members order-center
```
## 授予只读角色
在「项目管理」找到订单中心,进入该行的「权限中心」,建立角色、选择菜单权限,再给已存在的平台用户分配角色。下面的命令假设 `alice` 已存在、`order:order:list` 已由[清单同步](https://kaiwu.shengzhiweilai.online/config)登记。
```bash
./kaiwu access role-create order-center auditor --name "Auditor"
./kaiwu access role-grant order-center auditor --permissions order:order:list
./kaiwu access member-set order-center alice --roles auditor
```
`role-grant` 整体替换这个角色的权限集合,`member-set` 整体替换该成员的角色,并默认将成员设为启用。修改已有对象前先读取当前值,保留仍需的权限。重新查询并用该用户实际登录;隐藏按钮(前端通过 `@/kaiwu` 的 `useCan` / `` 判断)和后端拒绝都要验证。
在产品主导项目中,产品演示身份(`mock-support/personas.ts`)对应的角色和初始权限可预先写在前端仓 `kaiwu/roles.yml`;首次执行 `./kaiwu project adopt <前端仓> --apply` 时会自动导入这些初始角色。后续如果管理员在平台调整过角色权限,重跑纳管或日常 `project sync` 默认会保留平台侧的修改,只有显式传入 `--with-access` 才会再次计划角色变更。

## 给订单表加行级过滤
在 AI 辅助编写业务接口时,最容易出现的隐蔽漏洞是“只加了菜单按钮权限,却漏掉了行级数据过滤”,导致同项目内的普通员工能看到或越权修改他人数据。Kaiwu 将行级数据范围做成跨 Gateway 与业务服务的标准防线:
- **5 种固定范围与多角色并集**:支持 `ALL`、`DEPT_AND_CHILD`、`DEPT`、`SELF`、`CUSTOM_DEPT`(可选含下级),多角色自动取并集,未配置时默认收窄为 `SELF`。
- **请求链路零回调**:System 预计算权限与数据范围快照,Gateway 将归约后的 `ds` 声明写入 60 秒签名 Context;业务服务不回调平台。
- **SQL 层自动按表拦截与门禁防漏**:在后端 `domain` 模块引入 `com.kaiwuzaidao:kaiwu-data-scope:0.2.0`,把拦截器放在分页拦截器之前,并在 `kaiwu/data-scopes.yml` 声明受控表(打包进 `META-INF/kaiwu/`,共享表需显式写入 `exempt`)。表配备带索引的 `owner_user_id`、`owner_dept_id`,由 Starter 插入时自动填充;归属转移走 `DataScopes.reassign`,后台任务显式通过 `DataScopes.unrestricted("理由", ...)` 记录审计旁路,并由随仓的 `DataScopeConventionTest` 检查受控表的归属字段和索引、拦截 `JdbcTemplate` 源码中出现受控表名,并提示疑似漏声明的列表、分页和导出接口。
同步资源后,在项目角色上设置本人、本部门或指定部门等范围,并用两种归属的数据比较列表、分页总数以及越权更新的影响行数。[数据范围接入代码][rows] · [平台规则][scope]
# 清单同步与配置移交
平台清单可跟随项目协作方式放在对应仓库:**传统双仓项目(`project new`)默认放在后端 `kaiwu/`**;**产品主导项目(从 `kaiwu-web-starter` 起步并经 `project adopt` 纳管)维护在前端 `kaiwu/`**,前端 Mock 直接读取该目录,后端通过 `kaiwu/frontend-manifests` 指向前端清单。
下面以订单状态为例,在项目清单的 `kaiwu/dicts.yml` 添加列表项,将 `order-center` 换成自己的项目编码。若文件仍是初始空列表 `[]`,用下面的内容替换它。业务数据保存稳定值 `PENDING`,页面从字典读取标签(可通过 `@/kaiwu` 的 `useDict` 读取)。
```yaml
- dictCode: order-center.order_status
name: Order status
items:
- value: PENDING
label: Pending
color: processing
default: true
```
在入口仓运行第一条命令预览整份计划;核对目标、项目和全部资源后,再运行第二条。产品主导项目将清单目录换成前端仓路径即可(首次纳管用 `project adopt` 自动导入并同步 `roles.yml`,后续复跑 `project sync` 默认保留平台已调整过的角色,显式传入 `--with-access` 才同步角色变更):
```bash
./kaiwu project sync ../business/order-center-service
./kaiwu project sync ../business/order-center-service --apply
```
| 清单目录 `kaiwu/` 下的文件 | 用途 |
| --- | --- |
| `menus.yml`、`dicts.yml`、`configs.yml` | 菜单与按钮、字典、受管参数;参数在使用处提供默认值。 |
| `jobs.yml`、`i18n.yml` | 任务声明和项目多语言资源。 |
| `data-scopes.yml`、`roles.yml` | 数据范围资源和角色授权;首次纳管时自动导入初始角色,日常变更需显式加 `--with-access` 预览并核对。 |
| `workflows/`(可选) | 业务流程定义与绑定清单,独立启用 Workflow 服务后通过 `./kaiwu workflow sync <前端仓>` 预览或导入。 |
在项目作用域的字典页查到稳定值,再切换用户语言检查业务页面。同步会新增资源、更新清单负责的字段,并保留已有参数的当前值。Kaiwu 采用**项目作用域隔离的引用式国际化**(`scope_id` 区分平台与各业务项目):项目管理员维护本项目菜单、字典与错语译文时,无需拥有平台全局文案权限,也不会把其他项目的词条下发到无关用户的浏览器。清单中移除的条目会在计划中列出,删除操作需要到配置移交页逐项确认。全局默认和内置 `system` 项目由平台维护。[受管参数][params] · [同步规则][sync]

## 跨环境移交
很多团队在「开发 → 测试 → 生产」迁移菜单、字典、角色授权与定时任务时,只能靠手工导出 SQL 或在控制台重配一遍,极易因为环境主键 ID 不一致、漏配数据范围或误把测试任务直接跑在生产而出错。
在源环境「项目权限中心 → 配置移交」导出移交包,再到目标环境同名项目导入,整个过程按业务键对齐并具备四重安全边界:
- **6 类配置一次快照打包**:JSON 移交包内置与仓库 `kaiwu/` 同格式的 `dicts.yml`、`configs.yml`、`menus.yml`、`roles.yml`(含角色的 `dataScopes` 数据范围)、`jobs.yml` 与 `i18n.yml` 并附带 `sha256` 摘要;敏感配置自动跳过并写入 `warnings`,导出的 YAML 也可以直接覆盖回业务仓库随 Git 提交。
- **业务键对齐,不耦合数据库 ID**:菜单按权限码/路由/目录路径匹配,指定部门的数据范围按部门编码(`deptCode`)导出,无需手工对账各环境主键。
- **三方基线比对 + 409 并发守卫**:导入前先计算「上次成功移交基线 × 本次移交包 × 目标当前状态」的差异计划(`plan`)与哈希;执行(`apply`)时若发现计划之后目标环境被人改过,直接返回 409 拒绝覆盖。
- **风险分级确认防误操作**:普通配置默认应用(保留目标环境运营修改过的参数当前值);**角色授权(`ACCESS`)默认关闭,启用后按组追加;源环境已删条目(`REMOVED_AT_SOURCE`)须逐项勾选**,目标环境自增条目只报漂移不误删;**新建定时任务导入后一律默认停用**并校验目标环境是否有在线 Handler;成员与密钥留在各自环境,每次移交均记入审计与移交记录。[移交包范围][handover]

# 待办、消息与定时任务
站内信(`NotificationClient`)是**不可变事实通知**,只区分已读/未读;统一待办(`TodoClient`)则代表**随业务状态动态消失的待处理事项**,由业务服务按 `(项目, bizKey, 处理人)` 幂等打开与关闭,避免“单据已审批,平台工作台待办却消不掉”的脱节,也无需每个业务系统自建待办中心。两者共用同一份项目服务凭据,失败只记日志不阻断业务事务。[SDK 接入配置][sdk]
## 跟踪一张审批单
```java
String key = "approval:" + order.getNo();
todoClient.open(approverId, key, "订单待审批");
// 或签:任一人通过后 close(key) 关闭全部处理人待办
// 会签:每人办理完只关闭自己的待办
todoClient.close(key, approverId);
```
把业务单号固定在 `bizKey` 中,重复投递只更新内容而不产生重复待办,原生支持**或签(`close(key)`)、会签(`close(key, userId)`)、撤回取消(`cancel(key)`)、带截止时间逾期置顶**以及超期未办自动兜底清理。验收时用审批人登录工作台,重复投递同一事项,检查待办数量;办结后检查它从待办列表移出。用 `NotificationClient` 投递站内信,在接收人的通知中心核对标题、内容和已读状态。[待办契约][todo]
## 让业务服务按时执行任务
Platform 调度器不执行任意 Java 类名、Shell 或 URL,只触发业务项目主动上报的固定 Handler,并通过**中央租约抢占 + 协作式 `fencingToken()` / `assertLeaseActive()` 栅栏**让处理器在失去租约后停止后续写入:
1. 在业务后端实现 `ProjectScheduledTaskHandler`。`taskType()` 返回稳定的任务类型,例如 `report.daily`;`execute(context)` 复用业务服务。
2. 启用 `kaiwu.starter.scheduler.enabled`,配置项目身份和调度凭据。服务启动后上报 Handler。
3. 在 `kaiwu/jobs.yml` 声明相同任务类型,运行 [清单预览与同步](https://kaiwu.shengzhiweilai.online/config)。在平台调度页核对 Cron 和时区,再启用任务。
4. 查看执行记录,在业务库核对一次预期结果。任务语义为 at-least-once,用 `context.executionId()` 或任务 ID 与计划时间做幂等;长任务在批次间检查 `context.assertLeaseActive()`。[调度与租约][sdk]
# 文件存储与 Excel
业务后端按需引用 Maven Central 上的 `com.kaiwuzaidao` 组件,三个组件在本版都使用 `0.2.0`。`kaiwu-system-starter` 提供平台接入和可选的存储客户端,`kaiwu-data-scope` 用于数据范围过滤,`kaiwu-excel` 用于读写工作簿。[Starter][sdk] · [数据范围][rows] · [Excel][excel]
## 给项目绑定存储
平台管理员先在「对象存储」配置存储账号。下面在入口仓目录操作,以已有账号 `assets` 和项目 `order-center` 为例,执行前替换为实际名称。先完成 [CLI 登录](https://kaiwu.shengzhiweilai.online/after-generation),再调用 System 脚本。
```bash
cli=./workspace/kaiwu-system-service/scripts/kaiwu.sh
"$cli" storage accounts
"$cli" storage test assets
"$cli" storage bind order-center --account assets --max-mb 10 --types image/png,image/jpeg
"$cli" storage bindings order-center
```
v0.2.0 的 Gateway 缺少部分存储管理路由。如果用管理员账号查询存储账号或绑定仍返回 404,请查看[路由修复进展](https://github.com/kaiwuzaidao/kaiwu-gateway-service/pull/1)。
连通性测试会写入并删除一个探测对象。在项目后端按 SDK 文档启用对象存储,选用 `kaiwu` 提供方获取项目范围的临时凭据,这套架构有三个工程优势:
- **长期密钥不出平台**:阿里云 OSS / MinIO 等长期 AK/SK 加密保存在 System 内,业务服务通过服务凭据仅换取限定到 `{bucket}/{projectCode}/*` 前缀的 STS 临时凭据(后台自动预取与续签,不阻塞业务请求)。
- **文件字节不经平台中转**:上传与预签名下载直连对象存储,System 不成为流量瓶颈与数据汇集点。
- **只存引用不固化 URL**:业务库仅保存 `storage_ref` 与 `object_key`,切换存储绑定后,只要原绑定和对象仍可用,历史附件就能沿原引用读取,无需在切换时迁移。
需要全项目统一的文件登记台账时,参考 Starter 仓的 `docs/storage-file.sql`,在业务仓中追加建表迁移并开启 `StoredFileService`,自动支持上传确认、软删除缓冲与过期孤儿清理任务(`kaiwu.file.purge`)。由业务接口校验文件归属和用户权限,用项目成员上传小图并读取,再用无访问权的账号验证读取被拒,绑定改为 `READ_ONLY` 时另测写入被拒。[配置示例][storage] · [文件登记契约][registry]
## 给订单列表加 Excel 导入导出
在业务 domain 模块引入 `com.kaiwuzaidao:kaiwu-excel:0.2.0`。组件针对企业常见表格风险内置了防护:仅接受未加密单 Sheet XLSX、严格校验顺序表头、**拒绝公式注入**、限制 ZIP 条目数(最多 256)与展开大小(16 MiB),并在查询超限时直接报错而不静默截断。以下是业务代码片段,`headers` 的顺序就是模板契约,`ExcelTable` 来自 `com.kaiwu.excel.ExcelTable`。
```java
var headers = List.of("订单号", "金额");
byte[] template = ExcelTable.template(headers);
var rows = ExcelTable.read(file.getInputStream(), headers, 5 * 1024 * 1024, 5000);
var result = ExcelTable.process(rows, row -> validateAndSave(row));
```
`validateAndSave` 由业务实现,返回安全的错误说明或 `null`。用正确模板和一行错误金额做验收,确认返回错误行号。导出前执行与列表相同的筛选、权限和数据范围检查,查询最多取上限加一行,超限直接提示;校验完成后再调用 `ExcelTable.write`。订单号按文本处理可保留前导零。[支持的 XLSX 格式与限制][excel]
# 模型与项目助手
要让编码工具改 Java 或 React,请看 [AI 开发指南](https://kaiwu.shengzhiweilai.online/ai-development)。本页适用于平台管理员和业务后端开发者,目标是在平台内让已授权成员查询数据或执行一项业务操作。项目工厂生成基础脚手架可以独立使用。
## 为规划和回答选择模型
部署方先按[运行配置][nacos]设置允许的模型域名和受控出站代理。在「大模型配置」添加 OpenAI 兼容服务,填写服务地址、模型名及凭据,保存后测试连接。将 PLAN(识别和规划)与 ANSWER(生成回答)分别绑定到模型,两者可选同一个配置。已有默认模型时,未绑定的用途沿用默认配置。更换地址后重新处理凭据并测试;用一条已知答案的问题检查两阶段调用结果。[模型路由规则][models]

## 让助手查询订单
在业务后端声明一个固定能力,例如「按订单号查询状态」,指定能力码、版本、输入字段、结果字段及已有权限。用类型化读适配器调用业务查询,校验当前成员和数据范围,只返回允许展示的字段。在平台注册并审核能力版本后,用有权成员发起查询,再用无权成员验证拒绝。[能力声明][capabilities] · [类型化读操作][read]
## 让成员确认一次写入
写操作用 `TypedAgentWrite` 分开实现预览和执行。预览显示将修改的订单和字段,冻结版本等前置条件;用户确认后,执行函数在业务事务内再次校验归属、状态与版本。沿用运行时执行账本处理重试。验收时分别覆盖取消确认、预览后订单已变更、成功提交和重复提交。保留业务变更记录,交接只写脱敏摘要。[写操作契约与实现示例][write]
# 平台管理与日常操作
登录后先在工作台选择项目。个人用户在这里找入口、待办和通知;管理员可从管理菜单开通项目、授权成员和排查运行问题。看不到菜单时,先核对当前身份、所选项目和角色。
| 任务 | 怎么做 | 怎么确认 |
| --- | --- | --- |
| 开通业务项目 | 在项目管理登记名称、唯一编码,或在 CLI 对已有产品前端运行 `project adopt`,到项目工厂查看生成任务 | 新建项目可下载前后端 ZIP;`ADOPT_FRONTEND`(沿用已有前端)模式交付配套后端 ZIP,从工作台打开部署入口。[生成步骤](https://kaiwu.shengzhiweilai.online/after-generation) |
| 添加项目成员 | 先在组织和用户管理核对用户,再到项目权限中心选择成员和角色 | 让该成员重新进入工作台,检查能访问的项目、菜单、记录。[权限示例](https://kaiwu.shengzhiweilai.online/access) |
| 修改业务字典或参数 | 在对应项目查看字典项、受管配置与翻译资源;仓库维护的声明先预览差异 | 刷新业务页面检查标签、配置生效值与语言回退。[清单与移交](https://kaiwu.shengzhiweilai.online/config) |
| 处理待办或消息 | 从工作台进入待办,或在通知中心打开站内信 | 办结后检查待办数量,返回通知列表检查已读状态。[业务接入](https://kaiwu.shengzhiweilai.online/services) |
| 检查定时任务 | 在调度管理选择项目,核对任务类型、Cron、时区与启停状态 | 查最近一次执行时间、状态和业务结果。[调度接入](https://kaiwu.shengzhiweilai.online/services) |
| 检查文件服务或助手 | 在对象存储查看项目绑定,在模型配置检查连接与用途绑定 | 用项目成员完成一次[文件读取](https://kaiwu.shengzhiweilai.online/files)或[已授权的助手查询](https://kaiwu.shengzhiweilai.online/assistant) |
| 管理登录与授权 | 用户在个人资料管理自己的账号;设备授权页核对申请客户端,管理员在安全运营中心检查会话 | 撤销指定 CLI 会话后,从该客户端用 `./kaiwu whoami` 检查结果 |

排查业务页无法打开时,记录项目编码、入口路径、时间与 HTTP 状态,再沿[一次请求的路径](https://kaiwu.shengzhiweilai.online/how-it-works)定位。
# 数据库、部署与排错
## 选择数据库并初始化
| 用途 | 路径 |
| --- | --- |
| 本机首次体验 | `KAIWU_DB_TYPE=mysql ./kaiwu up` 创建 MySQL,平台启动时执行迁移。 |
| 已有 MySQL | 为平台准备独立空库,在受保护的运行配置中提供 `KAIWU_DB_HOST`、端口、库名、用户和密码,再初始化。 |
| 达梦 DM8 | 准备独立空 Schema,核对 UTF-8、页大小、大小写和兼容模式,按数据库手册完成迁移前检查。 |
| DBA 审阅初始化数据 | 在独立空库中先执行对应方言的 `mysql-01-ddl.sql` 或 `dm8-01-ddl.sql`,再执行同前缀的 `02-dml.sql` 文件查看种子数据。应用安装需要 Flyway 迁移历史,请另备空库交给 Compose 或 Helm 的迁移任务初始化。 |
v0.3.0 安装执行 V127 基线和 V128 增量,现有 v0.2.0 按原迁移流程应用 V128。旧 v0.1.0(V44)需要另建数据库;中间版本根据现有 Flyway 成功记录走对应升级路径。在已有数据的库里执行初始化脚本可能破坏数据,升级前保留可恢复的备份。[数据库配置][db] · [初始化 SQL 下载与说明][sql] · [按迁移版本升级][upgrades]
## 部署到服务器或 Kubernetes
- **单机 Compose**。在服务器备齐同版本产品仓,到 System 目录用 `./scripts/kaiwu-server-env.sh ../.kaiwu-server/runtime.env` 准备运行配置,再按手册组合基础与服务器 Compose 文件。配置反向代理和同源入口,分别部署业务后端和前端。最后从工作台登录并完成一次业务读取。[单机部署与外部 MySQL / Redis][server]
- **Kubernetes**。在入口运行 `./kaiwu deploy-init` 获取 GitOps 仓;Chart 位于 System 的 `deploy/helm/kaiwu`。固定镜像版本、准备命名空间和运行凭据,先用 `helm lint`、`helm template` 验证目标 values。安装后依次看迁移 Job、Pod 就绪、Gateway 路由和业务前端同源访问。[安装、升级与回滚][helm]
- **Nacos 开发环境**。System 与 Gateway 用各自的 Data ID,显式配置路由及 audience。对象存储与模型服务按实际域名配置出站策略。用 System 脚本的 `local-up` 对接该环境,用 `local-status` 和 `local-logs` 检查原生进程。[配置模板与启动参数][nacos]
## 常见问题
| 现象 | 从哪里查 |
| --- | --- |
| 第二套平台启动时端口冲突或连到旧库 | 用新的检出目录、项目名、对外端口及平台网络,保持该实例各次启动的配置一致。查看 `./kaiwu status`。 |
| 镜像拉取失败 | 看日志区分下载失败和源码构建失败;要主动走源码路径可执行 `./kaiwu up --build`。 |
| 无法登录或 CLI 指向别的平台 | 核对浏览器地址、CLI 的 `KAIWU_URL` 与 `./kaiwu whoami`。初次登录密码在本机查看。 |
| 工作台可用,业务页打不开 | 分别核对成员角色、项目入口、前端挂载位置和网关显式路由。查看 `./kaiwu logs --tail 100`。[请求路径](https://kaiwu.shengzhiweilai.online/how-it-works) |
| 更新配置后行为未变 | 核对项目编码、同步预览、实际目标环境和当前账号;需要重新登录时建立新会话。[配置移交](https://kaiwu.shengzhiweilai.online/config) |
暂停本机平台用 `./kaiwu down`,数据保留。`./kaiwu reset` 会删除本机平台数据,只在确实要清空时执行。
# CLI 命令索引
下列命令均加前缀 `./kaiwu`,在入口仓运行。大写参数替换为实际值,方括号表示可选项,斜线分隔备选命令或参数,实际执行时只选其中一种。首次体验从[安装](https://kaiwu.shengzhiweilai.online/start)开始。
## 运行平台
| 命令 | 用途 |
| --- | --- |
| `doctor` | 检查 Git、Docker Compose 等运行条件。 |
| `repositories` | 预览取仓来源及版本策略。 |
| `init [--with-deploy]` | 取回运行仓,可选一并获取部署仓。 |
| `up [--build / --no-build]` | 启动平台;发行版默认拉镜像,--build 从源码构建。 |
| `dev` | 用 Docker 跑基础设施,本机进程跑应用。 |
| `status` | 查看容器状态。 |
| `logs [--tail N] [-f]` | 查看最近日志,-f 持续跟随。 |
| `local-status / local-logs / local-down` | 查看、跟踪或停止本机应用进程。 |
| `credentials` | 在本机查看初始管理员凭据。 |
| `context-public-key` | 输出业务后端验签所用的网关公钥。 |
| `reload-routes` | 重新加载本机 Compose 受管路由。 |
| `down / reset` | down 停止并保留数据;reset 确认后删除本地平台数据。 |
| `deploy-init / help` | 获取可选 GitOps 仓;显示入口帮助。 |
## 会话与业务项目
| 命令 | 用途 |
| --- | --- |
| `login [--client NAME] [--local]` | 设备授权;--local 尝试本机免点击。远程由账号本人确认。 |
| `whoami / logout` | 查看身份或撤销 CLI 会话。 |
| `project new CODE --name NAME [--package PKG] [--description TEXT]` | 登记项目并生成一次基础脚手架。 |
| `project status CODE [--wait]` | 查看进度,可等待生成结束。 |
| `project pull CODE [--dir DIR]` | 下载、解压前后端并初始化两个 Git 仓。 |
| `project adopt FRONTEND [--apply]` | 登记已有产品前端、同步清单与首次角色,并生成配套后端仓(`ADOPT_FRONTEND`)。 |
| `project-up BACKEND [FRONTEND]` | 构建业务项目并接入本机平台。 |
| `project-down CODE` | 停止该业务栈,保留数据。 |
| `project entry CODE LABEL SERVICE_URL` | 登记业务入口名称和服务根地址。 |
| `project sync MANIFEST_REPO [--apply] [--with-access]` | 预览或同步 `kaiwu/*.yml`(支持后端仓或纳管后的前端仓);角色变更需显式加 `--with-access`。 |
| `workflow sync FRONTEND [--apply]` | 预览或导入业务前端 `kaiwu/workflows/` 流程清单(需启用兼容 Workflow 服务)。 |
## 成员与授权
| 命令 | 用途 |
| --- | --- |
| `access members CODE / access roles CODE / access permissions CODE` | 列出成员、角色或可授予的权限。 |
| `access role-create CODE ROLE --name NAME [--description TEXT]` | 创建项目角色。 |
| `access role-grant CODE ROLE (--permissions p1,p2 / --clear)` | 整体替换角色授权,--clear 清空。 |
| `access member-set CODE USER --roles r1,r2 [--disabled]` | 设置成员的完整角色集合,默认启用;--disabled 停用。 |
| `access member-remove CODE USER` | 移除项目成员。 |
## 产品与业务前端常用命令
下列命令在 `kaiwu-web-starter` 初始化仓或项目工厂生成的前端仓内执行:
| 命令 | 用途 |
| --- | --- |
| `node scripts/kaiwu-init.mjs --code CODE --name NAME [--example booking]` | 在 `kaiwu-web-starter` 初始化独立业务前端仓(默认空白,可选 `booking` 示例)。 |
| `pnpm dev` | 默认 Mock 模式启动开发服务,访问 `/__mock/` 切换演示身份并重置内存数据。 |
| `pnpm dev:real` | 关闭 Mock 并代理 `/api`、`/{code}-api`、`/{code}-svc` 到 `KAIWU_GATEWAY`(默认 `http://127.0.0.1:8088`)。 |
| `pnpm verify:mock` | 产品阶段全量自检:类型、字典、接入层 SHA-256、规则/场景/Mock 绑定、日志脱敏、约束与生产构建隔离。 |
| `pnpm verify` | 联调阶段全量自检:运行 `verify:mock` 并检查权限。配套后端在默认相邻目录,或设置 `KAIWU_SERVICE_DIR` 时,会逐码核对服务端注解。须查看实际输出确认完成三端比较。 |
| `pnpm test:scenarios` / `pnpm test:browser` | 执行 HTTP 验收场景 / 启动独立 Mock 跑 Chromium 交互验收。 |
| `pnpm test:proxy` | 默认用回显服务校验请求路径与项目头;设置 `KAIWU_GATEWAY` 时核对真实网关响应。 |
| `sh scripts/check-runtime-image.sh "$IMAGE" CODE` | 在已构建的生产前端镜像内校验首页与 `/__mock/` 返回 404。 |
## System 启动器扩展
以下命令前缀为 `./workspace/kaiwu-system-service/scripts/kaiwu.sh`。`local-up` 连接已配置的 Nacos 环境;`storage accounts` 列账号,`storage bindings [CODE]` 查绑定,`storage test ACCOUNT` 写入并删除探测对象。`storage bind CODE --account ACCOUNT` 支持 `--name`、`--max-mb` 和 `--types`;`storage bind-status ID --status ACTIVE` 可设置 ACTIVE、READ_ONLY 或 DISABLED。[按步骤绑定](https://kaiwu.shengzhiweilai.online/files)
远程 CLI 用 `KAIWU_URL` 选择平台;用 `KAIWU_REPOSITORY_REF` 固定取仓版本,Fork 使用 `KAIWU_REPOSITORY_BASE_URL` 指定仓库组。
# Kaiwu 是怎么运作的
10 分钟看懂 Kaiwu 的整体架构、请求链路与三条核心边界,帮你判断它是否适合你的团队。
## 1. 独立产品仓与起步模板,各自演进
Kaiwu 不是一个大杂烩单仓。入口仓只保留初始化脚本与编排,真正的代码按职责拆成**相互独立的 Git 仓库**:
| 仓库 | 角色 | 说明 |
| --- | --- | --- |
| `kaiwu-gateway-service` | **唯一外部入口**(8088) | 同源路由转发、JWT 与会话校验、签发内部 Context |
| `kaiwu-system-service` | **控制面后端** | 管理用户、项目、角色、菜单、字典、多语言与项目工厂 |
| `kaiwu-system-web` | **平台管理前端**(8000) | 工作台入口、权限中心、字典/多语言/配置管理界面 |
| `kaiwu-system-starter` | **业务服务 SDK** | 供业务后端引入的 Maven 依赖,负责本地验签与上下文注入 |
| `kaiwu-web-starter` | **产品前端起步仓** | 无平台依赖的独立 React 起步模板,内置 `/__mock/` 运行时与 `@/kaiwu` 接入层 |
| `kaiwu-deploy`(可选) | **GitOps 部署声明** | 使用 Kubernetes / ArgoCD 交付时按环境生成 |
## 2. 一次请求如何走通
以订单中心为例,浏览器从工作台打开 `/apps/order-center/`,页面请求同源的 `/order-center-api/`:
1. **Web Nginx 反代**:前端不直连后端,所有 `/api` 与业务 API 请求统一经 Nginx 转发给 **Gateway**。
2. **会话与成员校验**:**Gateway** 验证 Access JWT 与 Redis 在线会话;若访问业务项目接口,会向 **System** 核对当前用户是否为该项目的有效成员(带缓存)。
3. **签发 60 秒 Context**:**Gateway** 签发一枚有效期 60 秒、绑定目标服务 `audience` 的签名 Context,转发请求给业务后端。
4. **业务服务本地验签**:业务后端通过 **Starter SDK** **本地验签**并建立请求上下文,校验接口权限。业务查询可按项目配置的数据范围过滤记录。Context 验签在业务服务内完成。
| 异常现象 | 排查顺序 |
| --- | --- |
| 工作台缺少入口 | 检查项目成员是否启用、应用入口是否登记、前端挂载路径是否正确。 |
| 接口返回 401 | 检查会话是否有效、请求是否经过网关、目标服务的公钥与 `audience` 是否匹配。 |
| 接口返回 403 | 检查当前角色是否具备接口声明的权限码,授权变更后是否已重新建立会话。 |
| 列表返回为空 | 用同一账号核对所属组织、当前项目、行级数据范围与业务筛选条件。 |
## 3. 三条核心设计边界
Kaiwu 的绝大多数架构取舍,都可以归结为这三条边界:
1. **Gateway 不持有权限事实**:Gateway 只做身份、会话与路由;权限的唯一事实源在 **System**,避免两套权限数据互相漂移。
2. **Kaiwu 自己也是一个项目**:平台自身的成员、角色与菜单全部存放在内置项目 `project_code=system` 下,与业务项目走同一套表和授权链路,没有“特权旁路”。
3. **生成的业务项目必须能离开平台**:项目工厂对每个业务项目**只生成一次**——既可以由 `project new` 一次生成双仓(`BASIC_SCAFFOLD`),也可以让产品从 `kaiwu-web-starter` 先出前端,再由 `project adopt` 纳管并仅生成配套后端(`ADOPT_FRONTEND`)。交付后 Kaiwu 永不覆盖业务源码,平台升级与业务迭代互不牵制。
## 4. 产品与 AI 在哪一步参与,如何保证可交付
大模型能写出“能跑”的代码,但容易漏掉权限、数据库迁移、敏感日志脱敏与发布契约。Kaiwu 把产品探索与 AI 工程边界清晰分层:
- **产品先出正式前端(Mock 阶段)**:产品与 AI 从 `kaiwu-web-starter` 起步(内置 Umi Mock 运行时、501 兜底与 `/__mock/` 角色面板),通过 `@/kaiwu` 只读接入层调用平台能力(可自由更换 UI 组件库)。业务规则(`docs/business-rules.md`)与验收场景(`docs/acceptance-scenarios.md`)随源码提交,由 `pnpm verify:mock`、`pnpm test:scenarios` 与 `pnpm test:browser` 自动校验,在 `product` 分支验收后经 `handoff/*` MR 交给开发。
- **平台纳管与项目生成**:开发对已有产品前端运行 `./kaiwu project adopt <前端仓> --apply` 登记项目、导入清单和首次角色并生成配套 Spring Boot 后端;或使用受校验 `ProjectBlueprint` 由版本化模板确定性渲染双仓脚手架。
- **真实联调与跨环境交付**:业务仓自带 `AGENTS.md`、后端 `scripts/verify.sh` 与前端 `pnpm verify` 门禁。后端权限注解、前端按钮与 `kaiwu/menus.yml` 必须三端同码,`DataScopeConventionTest` 检查归属字段与索引,并提示疑似漏声明的接口;前端使用 `pnpm dev:real` 走 Gateway 联调,生产构建确保 `/__mock/` 返回 404。上线阶段,代码通过独立仓库与 GitOps 交付,字典、菜单、参数、角色授权、定时任务与项目级引用式多语言则通过 `project sync` 与「配置移交」在测试和生产环境间可控对齐。
## 5. 开箱即用的企业底座能力
除了项目工厂与双仓交付机制,Kaiwu 还为所有接入项目提供统一的平台基础能力:
- **MySQL 与达梦 DM8 双数据库支持**:平台控制面首次部署原生可选 MySQL 或国产达梦 DM8(配备独立 `kaiwu-dm-migrator` 与实例参数预检)。
- **跨环境配置移交(ADR 0042)**:6 类 YAML 全量快照 + 三方基线 diff 预览,角色授权按组确认、删除逐项勾选、新建定时任务默认停用。
- **按角色 × 部门的行级数据范围(`kaiwu-data-scope`)**:Gateway 在签名 Context 携带 `ds`,业务服务在 SQL 层自动注入隔离条件,零同步回调。
- **STS 对象存储与安全 Excel**:长期密钥加密留在平台,业务只取限定前缀的 STS 临时凭证且只存 `storage_ref + object_key`;`kaiwu-excel` 防公式注入与 ZIP 炸弹。
- **统一待办与受控 AI 助手**:`TodoClient` 按业务键表达或签/会签并随业务闭环;AI 助手支持 `PLAN / ANSWER` 双模型路由、按权限查询与写前预览确认。
## 下一步
- [5 分钟快速安装并登录](https://kaiwu.shengzhiweilai.online/start)
- [生成并运行第一个业务项目](https://kaiwu.shengzhiweilai.online/after-generation)
- [查看仓库与版本地图](https://kaiwu.shengzhiweilai.online/repos) · [Starter 验签约定][sdk]
# 仓库与版本
首次安装可选择最新稳定版标签,本手册以 `v0.3.0` 为例。入口与产品仓使用同名标签。执行 `./kaiwu repositories` 检查来源和版本,`./kaiwu init` 取回运行仓。System 的版本清单决定具体仓库;`workspace/.kaiwu/workspace.lock` 记录本次检出结果。
| 你要修改什么 | 去哪里 |
| --- | --- |
| 本机取仓、启动与统一命令 | 入口仓 `kaiwu`([Gitee][gitee] · [GitHub][github]) |
| 项目工厂、平台接口、数据库与 Helm | `workspace/kaiwu-system-service` |
| 会话验证与业务 API 路由 | `workspace/kaiwu-gateway-service` |
| 工作台、权限中心和管理界面 | `workspace/kaiwu-system-web` |
| 业务后端接入、数据范围和 Excel | `workspace/kaiwu-system-starter` |
| 产品前端独立起步仓(Mock 演示、规则契约与 `@/kaiwu`) | [kaiwu-web-starter][starter] |
| 环境与应用交付声明 | `./kaiwu deploy-init` 获取的 `kaiwu-deploy` |
| 订单、设备预约等具体领域功能 | `project pull` 取回的业务双仓,或由 `kaiwu-web-starter` 起步后经 `project adopt` 纳管配对的前后端仓 |
已有安装的升级需要核对数据库迁移与版本配置,按[升级手册][upgrades]执行。
查某项行为时,先对照运行版本,再读对应仓的 `AGENTS.md`、`README.md` 和测试。登记项目、下载脚手架和维护生成后的业务代码分别见[项目交付](https://kaiwu.shengzhiweilai.online/after-generation)与[业务开发](https://kaiwu.shengzhiweilai.online/business)。[发行说明][release]
# 适用场景
团队已有多个业务后台,想让员工从一个工作台进入,并在一处管理成员、角色、字典和通知时,可把这些公共能力交给 Kaiwu。每个业务项目仍拥有独立代码、数据和发布节奏。
- **产品直出正式前端**:不想再走“画原型 → 前端重写 → 联调扯皮”,产品经理可用 AI 从 `kaiwu-web-starter` 先做出可切角色的 Mock 前端并固化规则与场景,确认后经 `project adopt` 纳管并由后端在同一前端仓接上真实 API,参见[产品即前端交接](https://kaiwu.shengzhiweilai.online/business#product-handoff)。
- **刚开始一个项目**:[从起步仓或项目工厂生成并运行项目](https://kaiwu.shengzhiweilai.online/after-generation),再在业务仓[开发第一个功能](https://kaiwu.shengzhiweilai.online/business)。教程用设备预约和订单列表举例。
- **管理多团队与多环境交付**:按项目设置身份、角色与 SQL 层[行级数据范围](https://kaiwu.shengzhiweilai.online/access);通过 `project sync` 把仓库清单同步到平台,在测试到生产间通过 6 类 YAML 全量快照与三方基线比对[跨环境移交配置](https://kaiwu.shengzhiweilai.online/config)。
- **企业级通用能力免重复造轮子**:直接沿用统一待办与租约调度([业务接入](https://kaiwu.shengzhiweilai.online/services))、密钥不出平台的 STS 对象存储与安全 Excel([文件与表格](https://kaiwu.shengzhiweilai.online/files)),平台首次部署原生支持 **MySQL 或国产达梦 DM8**([数据库与部署](https://kaiwu.shengzhiweilai.online/operations))。
- **用 AI 协作开发与受控对话接入**:给编码工具仓库、范围、验证命令和完成条件,参见[可复制的任务示例](https://kaiwu.shengzhiweilai.online/ai-development)。在平台内按成员权限与数据范围开放业务查询或写前预览确认时,按[助手能力接入](https://kaiwu.shengzhiweilai.online/assistant)配置。
# 在线试用
[进入 System 工作台 →][trial]{target="_self"}
点击后会以共享体验账号 **demo-admin** 进入 System 工作台。你可以先浏览平台菜单,也可以从工作台打开[官网改版项目][project]。进入业务项目后,左侧菜单来自当前账号的项目授权,任务、页面与里程碑来自这个项目自己的业务库。
1. 在「改版任务」里打开「联调官网在线体验入口」,查看负责小组、关联页面和验收标准。选择一个新状态,点「保存进度」,刷新后可以读回结果。
2. 进入「交付里程碑」,点某个阶段的「查看任务」,核对具体事项和完成数。「页面清单」可以按官网页面查看对应任务。
3. 打开「平台能力」,对照继承的平台品牌和状态字典、项目覆盖的每页条数,以及附件存储的绑定状态。
4. 「成员管理」和「角色授权」沿用 Kaiwu 的项目权限。可以给练习成员更换角色,再刷新核对。要查看平台级管理菜单,可从项目总览返回 System 工作台。
所有访客共享一个项目,请使用虚构资料。体验数据每天北京时间 **04:00** 恢复。共享账号的密码和会话由系统管理。
## 想体验无平台的“产品先出 Mock 前端”?
上方的在线共享环境运行的是带真实后端与数据库的生产构建(按生产隔离约束,构建产物中已剥离 `/__mock/`)。如果你想亲自体验产品经理无需装平台、直接在本机切换角色并运行双人业务演示的流程,可在 `kaiwu-web-starter` 运行 `--example booking` 后打开 `/__mock/`,步骤见[产品先做前端与纳管](https://kaiwu.shengzhiweilai.online/after-generation#product-first)和[AI 协作开发指南](https://kaiwu.shengzhiweilai.online/ai-development#product-prompt-section)。
[project]: https://demo.kaiwu.shengzhiweilai.online/experience/project
[trial]: https://demo.kaiwu.shengzhiweilai.online/experience?start=system
[github]: https://github.com/kaiwuzaidao/kaiwu
[gitee]: https://gitee.com/wujm12138/kaiwu
[starter]: https://github.com/kaiwuzaidao/kaiwu-web-starter
[release]: https://github.com/kaiwuzaidao/kaiwu/releases/tag/v0.3.0
[quickstart]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/QUICKSTART.md
[factory]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/PROJECT_FACTORY.md
[adopt]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/adr/0048-adopt-existing-frontend.md
[access]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/PROJECT_ACCESS.md
[scope]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/DATA_SCOPE.md
[sync]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/adr/0036-platform-manifest-sync.md
[handover]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/adr/0042-project-config-handover.md
[params]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/MANAGED_PARAMETERS.md
[todo]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/UNIFIED_TODO.md
[sdk]: https://github.com/kaiwuzaidao/kaiwu-system-starter/blob/v0.3.0/README.md
[excel]: https://github.com/kaiwuzaidao/kaiwu-system-starter/blob/v0.3.0/excel/README.md
[rows]: https://github.com/kaiwuzaidao/kaiwu-system-starter/blob/v0.3.0/data-scope/README.md
[storage]: https://github.com/kaiwuzaidao/kaiwu-system-starter/blob/v0.3.0/docs/OBJECT_STORAGE.md
[registry]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/adr/0041-project-file-registry.md
[models]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/adr/0043-agent-multi-model-routing.md
[capabilities]: https://github.com/kaiwuzaidao/kaiwu-system-starter/blob/v0.3.0/docs/AGENT_CAPABILITIES.md
[read]: https://github.com/kaiwuzaidao/kaiwu-system-starter/blob/v0.3.0/docs/AGENT_TYPED_READ.md
[write]: https://github.com/kaiwuzaidao/kaiwu-system-starter/blob/v0.3.0/docs/AGENT_TYPED_WRITE.md
[db]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/DATABASES.md
[sql]: https://github.com/kaiwuzaidao/kaiwu-system-service/releases/tag/v0.3.0
[upgrades]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/UPGRADING.md
[server]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/SERVER-DEPLOYMENT.md
[helm]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/KUBERNETES.md
[nacos]: https://github.com/kaiwuzaidao/kaiwu-system-service/blob/v0.3.0/docs/NACOS.md