# Everything is Suitable - 应用启动指南

## 概述

本指南提供了启动Everything is Suitable项目所有应用的详细步骤，包括Web管理前端、Uniapp小程序、后端API和测试环境。

## 前置要求

### 1. 系统要求

- **操作系统**：macOS、Linux或Windows
- **Node.js**：18.0.0或更高版本
- **Python**：3.10或更高版本
- **Java**：21或更高版本
- **Maven**：3.8或更高版本
- **PostgreSQL**：14或更高版本

### 2. 开发工具

- **IDE**：VS Code、IntelliJ IDEA或WebStorm
- **Git**：用于版本控制
- **浏览器**：Chrome、Firefox或Safari（用于E2E测试）

## 项目结构

```
everything-is-suitable/
├── everything-is-suitable-admin/    # Web管理前端（Vue 3 + TypeScript）
├── everything-is-suitable-uniapp/    # Uniapp小程序
├── everything-is-suitable-api/       # 后端API（Spring Boot）
└── everything-is-suitable-test/      # 统一测试平台
    ├── e2e/                        # TypeScript E2E测试
    ├── python_e2e/                  # Python E2E测试
    └── api/                         # Python API测试
```

## 启动步骤

### 1. 启动后端API（everything-is-suitable-api）

#### 1.1 配置数据库

```bash
# 启动PostgreSQL
brew services start postgresql

# 创建数据库
psql -U postgres
CREATE DATABASE everything_is_suitable;
CREATE USER everything_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE everything_is_suitable TO everything_user;
\q
```

#### 1.2 配置环境变量

创建 `everything-is-suitable-api/src/main/resources/application-local.yml`：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/everything_is_suitable
    username: everything_user
    password: your_password
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
  flyway:
    enabled: true
    locations: classpath:db/migration
```

#### 1.3 启动应用

```bash
cd everything-is-suitable-api

# 方式1：使用Maven启动
mvn spring-boot:run -Dspring-boot.run.profiles=local

# 方式2：使用IDE启动
# 在IntelliJ IDEA中打开项目
# 运行 EverythingIsSuitableApplication.java
```

#### 1.4 验证启动

```bash
# 检查API是否启动成功
curl http://localhost:8080/actuator/health

# 预期输出
{"status":"UP"}
```

### 2. 启动Web管理前端（everything-is-suitable-admin）

#### 2.1 安装依赖

```bash
cd everything-is-suitable-admin

# 安装Node.js依赖
npm install

# 安装Playwright浏览器
npm run test:install:e2e
```

#### 2.2 配置环境变量

创建 `.env.development-local`：

```env
NODE_ENV=development
VITE_APP_ENV=development-local
VITE_API_BASE_URL=http://localhost:8080
VITE_MOCK_ENABLED=false
```

#### 2.3 启动应用

```bash
# 方式1：使用npm启动
npm run dev:local

# 方式2：使用Vite直接启动
npx vite --mode development-local
```

#### 2.4 验证启动

```bash
# 检查Web应用是否启动成功
curl http://localhost:5174

# 预期输出：HTML页面内容
```

### 3. 启动Uniapp小程序（everything-is-suitable-uniapp）

#### 3.1 安装依赖

```bash
cd everything-is-suitable-uniapp

# 安装Node.js依赖
npm install

# 安装Playwright浏览器（用于H5测试）
npm install -D @playwright/test
npx playwright install --with-deps
```

#### 3.2 配置环境变量

创建 `.env.development`：

```env
NODE_ENV=development
VITE_APP_ENV=development
VITE_API_BASE_URL=http://localhost:8080
VITE_MOCK_ENABLED=false
```

#### 3.3 启动应用

```bash
# 方式1：使用npm启动（H5模式）
npm run dev:h5

# 方式2：使用HBuilderX启动（小程序模式）
# 在HBuilderX中打开项目
# 点击"运行" -> "运行到小程序模拟器"
```

#### 3.4 验证启动

```bash
# 检查Uniapp H5是否启动成功
curl http://localhost:5173

# 预期输出：HTML页面内容
```

### 4. 启动测试环境（everything-is-suitable-test）

#### 4.1 安装TypeScript E2E测试依赖

```bash
cd everything-is-suitable-test

# 安装Node.js依赖
npm install

# 安装Playwright浏览器
npm run test:install:e2e
```

#### 4.2 安装Python E2E测试依赖

```bash
cd python_e2e

# 安装Python依赖
pip install -r requirements.txt

# 安装Playwright浏览器
python -m playwright install --with-deps

# 配置环境变量
cp .env.example .env

# 编辑.env文件，设置正确的URL
# WEB_BASE_URL=http://localhost:5174
# UNIAPP_URL=http://localhost:5173
# API_URL=http://localhost:8080
```

#### 4.3 安装API测试依赖

```bash
cd everything-is-suitable-test

# 安装Python依赖（使用Poetry）
cd api
poetry install
```

## 完整启动流程

### 开发环境启动

```bash
# 终端1：启动后端API
cd everything-is-suitable-api
mvn spring-boot:run -Dspring-boot.run.profiles=local

# 终端2：启动Web管理前端
cd everything-is-suitable-admin
npm run dev:local

# 终端3：启动Uniapp小程序
cd everything-is-suitable-uniapp
npm run dev:h5

# 终端4：启动E2E测试（包含Spring Boot Actuator监控）
cd everything-is-suitable-test
npm run test:e2e:smoke
```

### 测试环境启动

```bash
# 终端1：运行TypeScript E2E测试
cd everything-is-suitable-test
npm run test:e2e:smoke

# 终端2：运行完整E2E测试（包含Actuator监控）
npm run test:e2e:full
```

# 终端2：运行Python E2E测试
cd everything-is-suitable-test/python_e2e
pytest

# 终端3：运行API测试
cd everything-is-suitable-test/api
poetry run pytest
```

## 端口说明

| 应用 | 端口 | 说明 |
|------|------|------|
| 后端API | 8080 | Spring Boot应用 |
| Web管理前端 | 5174 | Vite开发服务器 |
| Uniapp H5 | 5173 | Vite开发服务器 |
| Prometheus | 9090 | 监控服务 |
| Grafana | 3000 | 监控面板 |

## 环境变量说明

### 后端API环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| SPRING_PROFILES_ACTIVE | Spring配置文件 | local |
| SPRING_DATASOURCE_URL | 数据库URL | jdbc:postgresql://localhost:5432/everything_is_suitable |
| SPRING_DATASOURCE_USERNAME | 数据库用户名 | everything_user |
| SPRING_DATASOURCE_PASSWORD | 数据库密码 | your_password |

### Web管理前端环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| NODE_ENV | Node环境 | development |
| VITE_APP_ENV | 应用环境 | development-local |
| VITE_API_BASE_URL | API基础URL | http://localhost:8080 |
| VITE_MOCK_ENABLED | 是否启用Mock | false |

### Uniapp环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| NODE_ENV | Node环境 | development |
| VITE_APP_ENV | 应用环境 | development |
| VITE_API_BASE_URL | API基础URL | http://localhost:8080 |
| VITE_MOCK_ENABLED | 是否启用Mock | false |

### Python E2E测试环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| TEST_ENV | 测试环境 | dev |
| BASE_URL | Web应用URL | http://localhost:5174 |
| UNIAPP_URL | Uniapp应用URL | http://localhost:5173 |
| API_URL | API服务URL | http://localhost:8080 |
| HEADLESS | 是否无头模式 | true |
| BROWSER | 浏览器类型 | chromium |
| TIMEOUT | 超时时间（毫秒） | 30000 |
| RETRY_COUNT | 重试次数 | 2 |
| PARALLEL_WORKERS | 并行工作数 | 4 |
| LOG_LEVEL | 日志级别 | INFO |
| SCREENSHOT_ON_FAILURE | 失败时截图 | true |
| VIDEO_ON_FAILURE | 失败时录制视频 | false |
| TRACE_ON_FAILURE | 失败时追踪 | false |

## 常见问题

### 1. 端口被占用

```bash
# 查看端口占用情况
lsof -i :8080
lsof -i :5174
lsof -i :5173

# 杀死占用端口的进程
kill -9 <PID>
```

### 2. 数据库连接失败

```bash
# 检查PostgreSQL是否运行
brew services list | grep postgresql

# 启动PostgreSQL
brew services start postgresql

# 检查数据库是否存在
psql -U postgres -l
```

### 3. 依赖安装失败

```bash
# 清除Node.js缓存
npm cache clean --force

# 重新安装依赖
rm -rf node_modules package-lock.json
npm install

# 清除Python缓存
pip cache purge

# 重新安装依赖
pip install -r requirements.txt --no-cache-dir
```

### 4. Playwright浏览器未安装

```bash
# 重新安装Playwright浏览器
npx playwright install --with-deps

# 或使用Python安装
python -m playwright install --with-deps
```

## 下一步

启动所有应用后，您可以：

1. 访问Web管理前端：http://localhost:5174
2. 访问Uniapp H5：http://localhost:5173
3. 访问API文档：http://localhost:8080/swagger-ui.html
4. 运行E2E测试验证功能
5. 运行API测试验证接口

## 参考文档

- [everything-is-suitable-admin/README.md](file:///Users/zhangxiang/Codes/Gitee/everything-is-suitable/everything-is-suitable-admin/README.md)
- [everything-is-suitable-uniapp/README.md](file:///Users/zhangxiang/Codes/Gitee/everything-is-suitable/everything-is-suitable-uniapp/README.md)
- [everything-is-suitable-test/README.md](file:///Users/zhangxiang/Codes/Gitee/everything-is-suitable/everything-is-suitable-test/README.md)
- [python_e2e/README.md](file:///Users/zhangxiang/Codes/Gitee/everything-is-suitable/everything-is-suitable-test/python_e2e/README.md)

---

**文档版本**: 1.0.0
**更新日期**: 2026-01-26
**作者**: Zhang Xiang