# 快速开始

## 环境要求

- **JDK 21+**
- **MySQL 8.0+**（如使用 MySQL 5.7，需额外配置 [MySQL 5.7 兼容方言](#mysql-57-兼容方言)）
- **Node.js 18+**
- **npm 9+**

## 项目搭建

### 1. 克隆项目

```bash
git clone https://github.com/jiangood/open-admin.git
cd open-admin
```

### 2. 后端配置

#### 数据库

```sql
CREATE DATABASE open_admin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

修改 `src/main/resources/application.yml` 数据库连接：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/open_admin?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
```

#### 启动后端

```bash
# 编译
mvn clean compile

# 启动（开发模式）
mvn spring-boot:run

# 打包
mvn package -DskipTests
java -jar target/open-admin.jar
```

### 3. 前端配置

```bash
cd web
npm install
npm run dev
```

### 4. 访问系统

| 说明 | 地址 |
|------|------|
| 前端 | http://localhost:3000 |
| 后端 API | http://localhost:8080/change-this-servlet-context |
| 默认登录 | admin / Admin#2026!!! |

## Servlet Context-Path 配置

部署时如需自定义上下文路径，需前后端同步修改：

**后端** — `src/main/resources/application.yml`:
```yaml
server:
  servlet:
    context-path: /your-context-path
```

**前端** — `web/.env`:
```
SERVLET_CONTEXT=/your-context-path
```

（`SERVLET_CONTEXT` 由 UmiJS 插件 `common-plugin` 自动注入 `define` 和 `proxy`，业务项目 `config.js` 只需注册插件，无需手动配置。）

前端请求会自动带上 context-path 前缀（通过 axios `baseURL`）。对于 `<a>`、`<img>` 等不经过 axios 的硬编码 URL，需使用 `SysUtils.contextPath(path)` 手动拼接。

## 创建新模块

### 后端

1. **Entity** — `modules/xxx/entity/` 下创建实体类，继承 `BaseEntity`
2. **Repository** — `modules/xxx/repository/` 下创建 Repository 接口，继承 `BaseRepository`
3. **Service** — `modules/xxx/service/` 下创建 Service，使用构造器注入 Repository
4. **Controller** — `modules/xxx/controller/` 下创建 REST 接口

### 前端

1. 在 `web/src/pages/xxx/` 下创建页面组件
2. 在 `menu-lib.yml` 中配置菜单和权限

`src/main/resources/data/menu-lib.yml`:

```yaml
data:
  menus:
    - id: sys-user
      name: 用户管理
      path: /system/user
      icon: UserOutlined
      perms:
        - {name: 查询, code: query}
        - {name: 新增, code: save}
        - {name: 删除, code: delete}
        - {name: 重置密码, code: reset-password}
        - {name: 分配权限, code: grant-permission}
```

## 集成到已有业务项目

open-admin 作为可嵌入框架，可以直接作为依赖引入现有业务项目。

### 后端集成

在业务项目的 `pom.xml` 中添加：

```xml
<dependency>
    <groupId>io.github.jiangood</groupId>
    <artifactId>open-admin</artifactId>
    <version>${open-admin.version}</version>
</dependency>
```

然后在 `application.yml` 中配置数据源，项目启动后自动完成系统初始化（建表、默认菜单、管理员账号）。

### 前端集成

在业务项目的 `package.json` 中添加：

```json
{
  "dependencies": {
    "@jiangood/open-admin": "^1.0.0"
  }
}
```

引入后可直接使用 ProTable、字段组件、权限组件等框架组件，套用后台布局即可复用用户管理、角色管理、字典管理等全套管理页面。

### 按需使用

- **只后端不需要前端**：仅添加 Maven 依赖，通过 REST API 访问管理功能
- **只前端不需要后端**：仅添加 npm 依赖，对接自己的后端 API
- **全栈集成**：同时添加前后端依赖，开箱即用

## 常见问题

### 数据库连接失败

检查 MySQL 服务、连接配置和用户权限。

### 前端依赖安装失败

```bash
npm install --registry=https://registry.npmmirror.com
```

### 端口被占用

后端默认 8080，前端默认 8000，检查端口占用情况。

### MySQL 5.7 兼容方言

Hibernate 7.x（Spring Boot 4.x 内置）仅支持 MySQL 8.0+。如使用 MySQL 5.7，需在 `pom.xml` 添加 `hibernate-community-dialects` 依赖：

```xml
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-community-dialects</artifactId>
</dependency>
```

并在 `application.yml` 中配置兼容方言：

```yaml
spring:
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.community.dialect.MySQLLegacyDialect
```