生成第一个模块

StackRivet 的代码生成器不只写 CRUD。它从单张数据库表生成一个可审查的模块包：后端各层、前端页面、权限 seed SQL、OpenAPI 注解、测试骨架、模块 manifest 和 AI 可读模块上下文——全部遵守架构与安全规则。

生成器内置在管理端与 API 中；你不需要运行一个单独的工具。Preview 会创建不可变、按 hash 寻址的 bundle。你可以查看准确内容与 diff、下载同一个 ZIP，再把这个准确 hash Apply 到审查目录（默认 generated-output）。

开始之前

后端和管理端已运行（见安装）。
有一张可生成的数据库表。生成器从 MySQL 8.4 或 PostgreSQL 18.4 读取表。

第一次试用可以在本地 MySQL 容器里创建这张小表：

cd stackrivet-server
docker compose exec -T mysql mysql -ustackrivet -pstackrivet stackrivet <<'SQL'
CREATE TABLE IF NOT EXISTS biz_todo_item (
  id VARCHAR(32) NOT NULL,
  tenant_id VARCHAR(32) NOT NULL DEFAULT 'default',
  title VARCHAR(120) NOT NULL COMMENT 'Todo title',
  priority INT NOT NULL DEFAULT 3 COMMENT 'Priority',
  status VARCHAR(20) NOT NULL DEFAULT 'open' COMMENT 'Status',
  due_at DATETIME NULL COMMENT 'Due time',
  remark VARCHAR(500) NULL COMMENT 'Remark',
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted TINYINT(1) NOT NULL DEFAULT 0,
  PRIMARY KEY (id),
  KEY idx_biz_todo_item_tenant_status (tenant_id, status),
  KEY idx_biz_todo_item_due_at (due_at)
) COMMENT='Todo item tutorial table';
SQL

流程

选择表 → 导入元数据 → 配置字段 → 不可变 Preview
→ 审查内容/diff → 下载 ZIP 或 Apply 准确 hash → 审查并合并

1. 打开生成器

打开 http://127.0.0.1:5173/generator，必要时先登录。管理端导航里也可以进入 代码生成器。

点击导入表，选择 biz_todo_item，把 Strip prefix 填成 biz_、Module name 填成 todo、Package name 填成 com.stackrivet.demo.todo，再执行导入。生成器会读取列、类型、主键和注释，同时保留这些生成边界。

GET  /api/v1/generator/database-tables      # 浏览可用表
POST /api/v1/generator/tables/import        # 导入选中的表

这会创建 sr_gen_table 和 sr_gen_column 配置行。如果这张表已经导入过，API 会拒绝重复导入，除非请求覆盖导入；覆盖会按数据库元数据重建字段配置。

2. 配置字段

点击导入行上的配置。确认 Module name 是 todo、Feature name 是 todoItem、Package name 是 com.stackrivet.demo.todo；它们分别驱动前端目录、权限前缀和 Java 包。然后对每一列设置它在列表、表单、查询里的展示、校验、字典和控件类型。StackRivet 会按列类型给出合理默认值：

DB 类型	Java	控件
varchar / text	String	input / textarea
integer / bigint	Integer / Long	number input
decimal	BigDecimal（金额绝不用 double）	decimal input
boolean / tinyint(1)	Boolean	switch
date / datetime	LocalDate / LocalDateTime	date / datetime picker
`*_asset_id`	String	资产上传控件（自动识别）
`*_dict`	String	select

id、tenant_id、created_at、updated_at、deleted 默认不进普通表单。更严格的服务端合同会锁定 tenant_id、dept_id、created_by、updated_by 的表单开关，因为这些值来自可信运行时上下文；同时锁定 tenant_id、deleted、deleted_at 的列表开关，因为生成响应 DTO 不包含它们。dept_id、created_by、updated_by 的列表展示仍可配置。如果把某个字段标为查询条件，合并模块前请确认表上有匹配索引。

控件也会声明运行时依赖。资产控件需要 stackrivet-asset 以及 asset:asset:create、asset:asset:list；带 dictCode 的 select 需要 stackrivet-system 以及 system:dict:list。生成 manifest 只记录实际使用的依赖，权限 seed 会把依赖对应的现有 active 菜单权限授予部署角色。除非同时移除需要该依赖的控件，否则不要忽略依赖提示。

这张示例表可以保留 title、priority、status、due_at、remark 在表单中展示，并把 status、due_at 打开为查询条件，这样生成的列表页会有可用筛选项。

3. 审查生成的菜单与权限

生成器会产出权限 seed SQL，里面包含菜单项和模块的菜单、按钮、API 权限，因此默认就是锁住的。seed 与来源租户绑定，并包含必填的 __SR_ROLE_ID__ 部署占位符；改成 Flyway 迁移前，必须换成同一租户中 active、未删除的角色。权限模型见新增权限。

4. 先预览，再应用

点击预览。生成器总是先预览再写入。Preview 返回 expectedHash、模板版本、治理状态，以及每个文件的准确内容、内容 hash、当前目标 hash 与 unified diff。文件状态是 CREATE、MODIFIED 或 UNCHANGED。

POST /api/v1/generator/tables/{id}/preview
GET  /api/v1/generator/tables/{id}/bundles/{expectedHash}
POST /api/v1/generator/tables/{id}/apply

Apply 请求体必须绑定已经审查的 bundle：

{
  "expectedHash": "<Preview 返回的小写 SHA-256>",
  "overwriteModified": false
}

overwriteModified 默认是 false。如果目标在 Preview 后发生变化，Apply 会返回 stale/conflict 且零写入；此时必须重新 Preview，不能重试旧 hash。Apply 会先 stage 全部文件，再原子替换目标，失败不会留下半棵目录。

Community 默认保留 bundle 24 小时，每张表最多 5 个，单 bundle 最大 5 MiB，内容/diff 检查上限 1 MiB。运维可通过 stackrivet.generator 下的 bundle-root、 bundle-ttl、max-bundles-per-table、max-bundle-bytes 与 max-inspection-bytes 调整。

你得到什么

生成文件默认放在 generated-output/ 下；如果你配置了其他 output root，则以配置为准。

范围	文件
后端	`{Name}Entity`、`{Name}Mapper`、`{Name}Service` + `Impl`、`{Name}Controller`、Create/Update/Query DTO、Response VO
前端	`{resource}.api.ts`、列表页、表单 drawer，以及可自动发现的生成路由描述文件
治理	菜单 + 按钮 + API 权限 seed、OpenAPI 注解、基础测试、模块 manifest、AI 可读模块上下文

生成的后端遵守与手写模块相同的规则：Controller 不直接调 Mapper，DTO/VO 不复用实体，列表 API 分页（最大 pageSize 200），生成文件会带模板元数据和文件 hash，供升级路径使用。

生成之后

staging 模块包已经生成，但还没有自动进入运行中的应用。完整新手流程见生成模块手工落地实战：

选择目标 Maven 模块；如新建模块，同时更新 root reactor、BOM 和 stackrivet-app 依赖。
把后端文件从 generated-output/src/... 复制进该 Maven 模块。
替换同租户部署角色占位符，再把 generated-output/db/migration/<module>-<resource>__permissions.sql 改名为下一个 Flyway 版本，并放入 common/、mysql/ 或 postgresql/。
把 generated-output/frontend/src/... 复制进 stackrivet-admin-ui/src/...，其中包含 src/generated/routes/<module>-<resource>.ts。
核对生成路由描述文件的 path/permission 与 sr_sys_menu 一致；Admin UI 会在构建期自动发现，并对重复 path/name 直接失败。
先验证 RBAC、菜单可见性和 API 访问，再继续定制。

AI 工具可以读取生成的模块上下文来安全扩展业务；见 AI 编码工作流。

合并 staging 文件后，最小验证流程是：

cd stackrivet-server
./mvnw -pl <target-module> -am test
./mvnw -pl stackrivet-app -am package -DskipTests
java -jar stackrivet-app/target/stackrivet-app.jar

cd ../stackrivet-admin-ui
pnpm typecheck
pnpm dev

版本边界

Community 生成单表模块，并提供不可变 Preview、准确 ZIP 与原子 Apply。主子表、树表、多对多与升级兼容自动化在 Team 试点中仍标记为 Roadmap——见价格页。