项目结构

StackRivet 采用多个独立仓库组成的工作区，而不是 monorepo。每个仓库有自己的 git 历史、发布节奏和许可，可以单独克隆。

仓库

仓库	用途	技术栈
stackrivet-server	后端模块化单体	JDK 21 · Spring Boot 4.0.6 · MyBatis-Plus · Flyway
stackrivet-admin-ui	管理端前端	Vue 3.5 · Vite 8 · TypeScript 6 · Element Plus 2.14
stackrivet-site	官网与公开文档	Astro 6 · Starlight · TypeScript

使用、贡献和工程规则以公开仓库与本站文档为准。

管理端通过 HTTP 与后端通信：开发环境下，它把 /api/* 和 /actuator/* 代理到 http://127.0.0.1:8080。

后端模块

后端 reactor 共 16 个 Maven 模块：其中 15 个装配成可单独部署的应用（默认单体）；第 16 个 stackrivet-scheduler-snailjob 是为选择 SnailJob 的团队单独打包的按需启用调度适配器。每个模块职责清晰、互守边界（由 stackrivet-app 中的 ArchUnit 测试强制保障）。

模块	职责
stackrivet-bom	集中式依赖 BOM
stackrivet-parent	父 POM、编译器 release=21、插件管理
stackrivet-common	R<T>、PageR<T>、TraceIdHolder、BusinessException
stackrivet-security	认证、RBAC、数据权限上下文、令牌管理
stackrivet-system	用户 / 部门 / 岗位 / 角色 / 菜单 / 字典 / 参数管理
stackrivet-audit	操作 / 登录 / 异常日志，traceId 关联
stackrivet-asset	资产元数据 + StorageAdapter（Local、S3 兼容、阿里云 OSS）、signed URL、分片上传
stackrivet-generator	数据库自省、类型映射、模板渲染、带治理的写出
stackrivet-import-export	通过 EasyExcel、走异步任务的 Excel / CSV 导入导出
stackrivet-task	异步任务状态机：pending / running / success / failed / retrying / cancelled
stackrivet-observability	Actuator、Micrometer、traceId，可选 OpenTelemetry profile
stackrivet-plugin	模块 manifest 加载；权限 / 菜单 / 字典注册
stackrivet-cli	轻量 CLI：doctor
stackrivet-demo	工单 CRUD 示例，以及定时任务处理器示例
stackrivet-app	Spring Boot 入口；把每个模块装配成可运行应用；承载 ArchUnit 边界测试
stackrivet-scheduler-snailjob (可选)	单独打包的 SnailJob 2.0 调度适配器 + 只读管理端摘要

每一层都单向流动 —— Controller → Service → Domain → Mapper —— 实体永不越过持久化边界（跨边界用 DTO 和 VO）。

前端布局

src/
  api/          ← axios 客户端，封装 R<T> 响应信封
  features/     ← 功能目录（system / asset / generator / audit / task）
  generated/    ← 代码生成器输出（gitignored）
  layouts/      ← AdminLayout、LoginLayout
  router/       ← Vue Router 路由 + 守卫
  stores/       ← Pinia stores
  styles/       ← tokens.scss、element-overrides.scss、reset、utilities、fonts
  utils/        ← 共享 TypeScript 工具
  views/        ← 页面级视图

前端使用 StackRivet 设计系统，它覆盖了 Element Plus 的默认观感。设计 token 是颜色、间距、圆角的唯一事实源 —— 页面组件里不出现内联 hex 或像素值。

新东西放哪里

你想新增……	放在……
一个业务模块	用产品内置的代码生成器 /api/v1/generator —— 不要手搓
一个权限	先在模块 manifest 中声明，再给 Controller 加注解
一张数据库表	在所属模块中增加 Flyway 迁移
一个前端组件	放在对应的共享或功能区域
一个设计 token	扩展设计 token 层 —— 不要内联