alwaysApply: true

工程上下文

本文件由 /spec:init 命令自动生成，描述项目整体结构与约定

1. 应用概况

应用名: Forge Admin
简介: 基于Vue3 + Spring Boot的企业级中后台管理框架，微内核插件化架构
技术栈: Java 17 / Spring Boot 3.2.9 / Vue 3.5 / Naive UI 2.42 / Vite 7
构建工具: Maven (后端) + pnpm (前端)
数据库: MySQL 8.0+ / Redis 6.0+
版本: 1.0.0

2. 技术栈详情

2.1 后端技术栈

技术/框架	版本	用途
Spring Boot	3.2.9	基础框架
MyBatis-Plus	3.5.7	ORM框架
Sa-Token	1.38.0	认证授权
Redisson	3.34.1	分布式锁
Hutool	5.8.31	Java工具库
Flowable	7.0.1	工作流引擎
MapStruct-Plus	1.4.4	对象映射
EasyExcel	4.0.2	Excel处理
Velocity	2.3	模板引擎
SpringDoc	2.6.0	API文档
SnailJob	1.1.2	分布式任务调度
AWS SDK	2.25.15	对象存储
SMS4J	3.3.2	短信服务
Undertow	2.3.15	Web服务器

2.2 前端技术栈

技术/框架	版本	用途
Vue	3.5.20	前端框架
Naive UI	2.42.0	UI组件库
Vite	7.1.3	构建工具
Pinia	3.0.3	状态管理
Vue Router	4.5.1	路由管理
UnoCSS	66.4.2	原子化CSS
Axios	1.11.0	HTTP客户端
ECharts	6.0.0	图表库
BPMN.js	17.11.1	流程设计器
CodeMirror	6.0.1	代码编辑器
XLSX	0.18.5	Excel处理
Lodash-ES	4.17.21	工具函数库

3. 目录结构与模块职责

3.1 后端目录结构

forge/
├── forge-admin/                      # 主应用启动入口
│   ├── src/main/
│   │   ├── java/                     # 主程序入口
│   │   └── resources/
│   │       ├── application.yml       # 主配置文件
│   │       ├── application-dev.yml   # 开发环境配置
│   │       ├── sql/                  # SQL脚本
│   │       └── i18n/                 # 国际化资源
│   └── pom.xml                       # 依赖所有插件和starter
│
├── forge-flow/                       # 独立流程引擎服务
│
└── forge-framework/                  # 核心框架层
    ├── forge-dependencies/           # 统一依赖管理
    │
    ├── forge-plugin-parent/         # 插件集合（业务模块）
    │   ├── forge-plugin-system/      # 系统管理插件
    │   │   ├── controller/           # 控制器层
    │   │   ├── service/              # 服务层
    │   │   │   └── impl/             # 服务实现
    │   │   ├── mapper/               # 数据访问层
    │   │   ├── entity/               # 实体类
    │   │   ├── dto/                  # 数据传输对象
    │   │   ├── vo/                   # 视图对象
    │   │   ├── constant/             # 常量定义
    │   │   └── listener/             # 事件监听器
    │   ├── forge-plugin-generator/   # 代码生成插件
    │   ├── forge-plugin-job/         # 定时任务插件
    │   ├── forge-plugin-message/     # 消息中心插件
    │   └── forge-plugin-flow/        # 流程引擎插件
    │
    └── forge-starter-parent/        # 启动器集合（技术能力）
        ├── forge-starter-core/       # 核心功能
        ├── forge-starter-web/        # Web层封装
        ├── forge-starter-auth/       # 认证授权（Sa-Token）
        ├── forge-starter-orm/        # ORM封装（MyBatis-Plus）
        ├── forge-starter-cache/      # 缓存管理（Redis）
        ├── forge-starter-config/     # 配置中心
        ├── forge-starter-crypto/     # 加解密能力
        ├── forge-starter-tenant/     # 多租户支持
        ├── forge-starter-file/       # 文件存储（OSS）
        ├── forge-starter-excel/      # Excel处理
        ├── forge-starter-job/        # 任务调度
        ├── forge-starter-log/        # 日志管理
        ├── forge-starter-id/         # ID生成器
        ├── forge-starter-idempotent/ # 幂等性控制
        ├── forge-starter-datascope/  # 数据权限
        ├── forge-starter-websocket/  # WebSocket支持
        ├── forge-starter-trans/      # 分布式事务
        ├── forge-starter-social/     # 社交登录
        ├── forge-starter-api-config/ # API配置
        ├── forge-starter-message/    # 消息服务
        └── forge-flow-client/        # 流程客户端

3.2 前端目录结构

forge-admin-ui/
├── src/
│   ├── api/              # API接口定义
│   ├── components/       # 公共组件
│   │   ├── ai-form/           # AI表单组件
│   │   ├── ai-modal/          # AI弹窗组件
│   │   ├── bpmn/              # BPMN流程设计器
│   │   ├── common/            # 通用组件
│   │   ├── file-upload/       # 文件上传
│   │   ├── form-designer/     # 表单设计器
│   │   ├── image-upload/      # 图片上传
│   │   ├── DictSelect.vue     # 字典选择器
│   │   ├── DictTag.vue        # 字典标签
│   │   ├── IconSelector.vue   # 图标选择器
│   │   └── ...
│   ├── composables/      # 组合式API
│   ├── layouts/          # 布局组件
│   ├── router/           # 路由配置
│   ├── store/            # Pinia状态管理
│   ├── stores/           # Pinia Store模块
│   ├── utils/            # 工具函数
│   ├── config/           # 配置文件
│   ├── styles/           # 样式文件
│   ├── views/            # 页面视图
│   │   ├── system/           # 系统管理页面
│   │   ├── flow/             # 流程管理页面
│   │   ├── generator/        # 代码生成页面
│   │   ├── message/          # 消息中心页面
│   │   ├── login/            # 登录页面
│   │   └── ...
│   ├── App.vue           # 根组件
│   └── main.js           # 入口文件
├── vite.config.js        # Vite配置
└── package.json          # 项目依赖

4. 模块依赖关系

4.1 后端模块依赖图

forge-admin (主应用)
├── forge-plugin-system (系统管理)
├── forge-plugin-job (定时任务)
├── forge-plugin-message (消息中心)
├── forge-plugin-generator (代码生成)
├── forge-flow-client (流程客户端)
└── starter集合:
    ├── forge-starter-web (Web能力)
    ├── forge-starter-auth (认证授权)
    ├── forge-starter-excel (Excel)
    ├── forge-starter-config (配置中心)
    ├── forge-starter-id (ID生成)
    └── forge-starter-crypto (加解密)

forge-flow (流程引擎服务)
├── forge-plugin-flow (流程插件)
└── starter集合

每个plugin模块依赖:
└── forge-starter-orm (MyBatis-Plus)
└── forge-starter-core (核心能力)

4.2 分层架构

后端标准分层

Controller层 (controller/)
    ↓ 接收请求、参数校验、协议转换
Service层 (service/)
    ↓ 业务编排、事务边界
Manager层 (manager/) [可选]
    ↓ 领域能力、单一职责、可复用
Mapper层 (mapper/)
    ↓ 纯数据访问（MyBatis-Plus）

Entity实体层:
- entity/    数据库表映射
- dto/       数据传输对象（请求参数）
- vo/        视图对象（响应数据）

前端标准分层

Views (views/)           # 页面视图
    ↓
Components (components/) # 可复用组件
    ↓
Composables (composables/) # 组合式API
    ↓
API Layer (api/)         # 接口调用
    ↓
Utils (utils/)           # 工具函数

5. 核心功能模块

5.1 系统管理插件 (forge-plugin-system)

用户管理：用户CRUD、用户分配角色
角色管理：角色CRUD、角色分配菜单权限
菜单管理：菜单树、权限标识
部门管理：部门树、数据权限
岗位管理：岗位CRUD
字典管理：字典类型、字典数据
参数配置：系统参数配置
通知公告：系统公告
日志管理：操作日志、登录日志
在线用户：在线用户监控
缓存监控：Redis缓存监控
定时任务：Quartz任务调度

5.2 代码生成插件 (forge-plugin-generator)

表管理：数据库表导入
字段管理：字段配置
代码生成：前端Vue、后端Java代码生成
模板管理：代码模板配置

5.3 流程引擎插件 (forge-plugin-flow)

流程设计：BPMN流程设计
流程部署：流程部署管理
流程实例：流程实例管理
任务管理：待办任务、已办任务
流程监控：流程监控面板

5.4 消息中心插件 (forge-plugin-message)

消息发送：站内信、邮件、短信
消息模板：消息模板管理
消息记录：消息发送记录

5.5 定时任务插件 (forge-plugin-job)

任务管理：Quartz任务CRUD
任务日志：任务执行日志
任务监控：任务执行监控

6. 常用命令清单

6.1 后端命令

# 编译整个项目
cd forge && mvn clean install

# 运行admin服务
cd forge/forge-admin && mvn spring-boot:run

# 运行flow服务
cd forge/forge-flow && mvn spring-boot:run

# 跳过测试编译
mvn clean install -DskipTests

# 指定环境运行
mvn spring-boot:run -Dspring-boot.run.profiles=dev

6.2 前端命令

# 安装依赖
cd forge-admin-ui && pnpm install

# 开发模式
pnpm dev

# 生产构建
pnpm build

# 代码检查和修复
pnpm lint:fix

# 预览构建结果
pnpm preview

6.3 数据库命令

-- 创建数据库
CREATE DATABASE forge DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

-- 导入初始数据
USE forge;
SOURCE /path/to/forge-admin/src/main/resources/sql/forge.sql;

7. 开发环境配置

7.1 后端配置 (application-dev.yml)

# 数据源配置
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3307/forge?useUnicode=true&characterEncoding=utf8
    username: root
    password: root

# Redis配置
  data:
    redis:
      host: localhost
      port: 6379
      # password: 
      database: 0

# 服务端口
server:
  port: 8580

7.2 前端配置 (.env.local)

# API代理配置
VITE_REQUEST_PREFIX=/api
VITE_HTTP_PROXY_TARGET=http://localhost:8580
VITE_FLOW_PROXY_TARGET=http://localhost:8581

8. 关键设计约定

8.1 数据库设计规范

所有业务表必须包含基础字段：id, tenant_id, create_by, create_time, create_dept, update_by, update_time
使用 utf8mb4 字符集，InnoDB 存储引擎
主键使用雪花ID（分布式ID）
高频查询字段建立索引，复合索引遵循最左前缀原则

8.2 逻辑删除与唯一键（强制）

用户可见主数据、配置、设计态元数据和业务单据默认增加 del_flag，实体必须显式声明 @TableLogic；Mapper XML 查询必须显式过滤 del_flag = 0。
没有“仅有效记录唯一”业务键的表，使用普通 TINYINT/Integer del_flag，取值 0 正常、1 删除，不要机械增加活跃唯一索引。
数值主键表需要“有效记录唯一、删除后允许同值重建”时，使用 BIGINT/Long del_flag、UNIQUE (tenant_id, 业务键..., del_flag) 和 @TableLogic(value = "0", delval = "主键数据库列名")；有效行写 0，删除后写当前行主键。
自定义单条或批量删除 SQL 必须与字段语义一致；主键墓碑表使用 SET del_flag = 主键列 WHERE del_flag = 0，禁止固定写 1。字符串主键表使用可容纳主键的字符串字段和专用 Mapper。
业务键要求跨删除历史永久唯一时，唯一索引不包含 del_flag。
禁止新增 logic_delete_active 生成列、函数/部分索引，或使用有效行 deleted_at = NULL 的唯一索引；MySQL 唯一索引允许多个 NULL，无法保证有效业务键唯一。

8.3 API设计规范

RESTful风格：
- GET /page - 分页查询
- GET /{id} - 详情查询
- POST / - 新增
- PUT / - 修改
- DELETE /{id} - 删除
统一响应：RespInfo.success(data) / RespInfo.error(msg)
敏感接口加密：使用 @ApiDecrypt / @ApiEncrypt 注解

8.4 代码生成规范

使用内置 forge-plugin-generator 生成CRUD模块
前端CRUD页面使用 AiCrudPage 组件
避免手写重复代码，使用代码生成器

8.5 前端开发规范

API调用使用 @/utils/request 工具
加密API调用使用 @/utils/encrypt-request
样式使用UnoCSS，避免自定义CSS
组件开发遵循现有组件模式
优先使用Naive UI组件

9. 项目统计

后端模块数量: 33个Maven模块
插件数量: 5个业务插件
启动器数量: 20个技术启动器
前端组件数量: 20+公共组件
主要功能模块: 6大功能模块

10. 快速开始

10.1 环境准备

# 检查Java版本（需要17+）
java -version

# 检查Node版本（需要18+）
node -v

# 检查pnpm版本（需要8+）
pnpm -v

# 检查MySQL版本（需要8.0+）
mysql --version

# 检查Redis版本（需要6.0+）
redis-server --version

10.2 后端启动

# 1. 创建数据库
mysql -u root -p
CREATE DATABASE forge DEFAULT CHARACTER SET utf8mb4;

# 2. 导入SQL脚本
USE forge;
SOURCE forge/forge-admin/src/main/resources/sql/forge.sql;

# 3. 配置数据库连接
cp forge/forge-admin/src/main/resources/application-dev.example.yml \
   forge/forge-admin/src/main/resources/application-dev.yml
# 编辑application-dev.yml，配置数据库和Redis

# 4. 启动服务
cd forge/forge-admin
mvn spring-boot:run

# 访问 http://localhost:8580

10.3 前端启动

# 1. 安装依赖
cd forge-admin-ui
pnpm install

# 2. 配置环境（可选）
cp .env.example .env.local
# 编辑.env.local配置API代理

# 3. 启动开发服务
pnpm dev

# 访问 http://localhost:5173
# 默认账号: admin / 123456

11. 注意事项

首次配置: 后端需要复制 application-dev.example.yml 为 application-dev.yml 并配置数据库和Redis
前端配置: 前端需要复制 .env.example 为 .env.local 配置本地环境
代码规范: 遵循 code-copilot/rules/coding-style.md 编码规范
领域规则: 遵循 code-copilot/rules/domain-rules.md 业务规则
渐进式开发: 使用 /propose 命令创建变更提案，遵循 No Spec No Code 原则
分支管理: 禁止直接提交到master分支，使用feature分支开发
代码生成: 优先使用代码生成器，避免手写CRUD代码

project-context.md 15 KB Vēsture Neapstrādāts

alwaysApply: true

工程上下文

1. 应用概况

2. 技术栈详情

2.1 后端技术栈

2.2 前端技术栈

3. 目录结构与模块职责

3.1 后端目录结构

3.2 前端目录结构

4. 模块依赖关系

4.1 后端模块依赖图

4.2 分层架构

后端标准分层

前端标准分层

5. 核心功能模块

5.1 系统管理插件 (forge-plugin-system)

5.2 代码生成插件 (forge-plugin-generator)

5.3 流程引擎插件 (forge-plugin-flow)

5.4 消息中心插件 (forge-plugin-message)

5.5 定时任务插件 (forge-plugin-job)

6. 常用命令清单

6.1 后端命令

6.2 前端命令

6.3 数据库命令

7. 开发环境配置

7.1 后端配置 (application-dev.yml)

7.2 前端配置 (.env.local)

8. 关键设计约定

8.1 数据库设计规范

8.2 逻辑删除与唯一键（强制）

8.3 API设计规范

8.4 代码生成规范

8.5 前端开发规范

9. 项目统计

10. 快速开始

10.1 环境准备

10.2 后端启动

10.3 前端启动

11. 注意事项

project-context.md 15 KB

Vēsture Neapstrādāts