# 新大洲车联网 CRM 系统 - 服务端启动说明

## 📋 项目简介

新大洲车联网 CRM 系统服务端，基于 Spring Boot 3.5.9 构建的微服务架构。

## 🔧 环境要求

- **JDK**: 17 或更高版本
- **Maven**: 3.6+ 
- **MySQL**: 5.7+ 或 8.0+
- **Redis**: 5.0+ 或 6.0+
- **IDE**: IntelliJ IDEA（推荐）或 Eclipse

## 📦 项目结构

```
xdz_server/
├── xdz-dependencies/          # 依赖管理模块
├── xdz-framework/            # 框架基础模块
├── xdz-module-user/          # 用户服务模块
│   ├── xdz-module-user-api/      # 用户服务 API（供其他服务调用）
│   └── xdz-module-user-server/   # 用户服务（端口：18080）
├── xdz-module-vehicle/       # 车辆服务模块
│   ├── xdz-module-vehicle-api/   # 车辆服务 API（供其他服务调用）
│   └── xdz-module-vehicle-server/  # 车辆服务（端口：18083）
├── xdz-module-message/       # 消息服务模块
│   ├── xdz-module-message-api/   # 消息服务 API（供其他服务调用）
│   └── xdz-module-message-server/  # 消息服务（端口：18082）
├── xdz-module-business/      # 业务服务模块
│   ├── xdz-module-business-api/   # 业务服务 API（供其他服务调用）
│   └── xdz-module-business-server/ # 业务服务（端口：18081）
│       └── 包含社区模块（社区功能已集成到业务服务中）
└── xdz-module-platform/     # 平台服务模块（预留）
```

## 🔗 服务依赖关系

### 模块编译依赖关系（Maven 依赖）

```
xdz-dependencies (依赖管理)
    ↓
xdz-framework (框架基础，依赖 xdz-dependencies)
    ↓
├── API 模块（可并行编译，无相互依赖）
│   ├── xdz-module-user-api
│   ├── xdz-module-vehicle-api
│   ├── xdz-module-message-api
│   └── xdz-module-business-api
│
└── Server 模块（依赖对应的 API 模块）
    ├── xdz-module-user-server
    │   └── 依赖：user-api, business-api
    │
    ├── xdz-module-vehicle-server
    │   └── 依赖：vehicle-api, user-api, message-api
    │
    ├── xdz-module-message-server
    │   └── 依赖：message-api, vehicle-api
    │
    └── xdz-module-business-server
        └── 依赖：business-api, vehicle-api, message-api, user-api
```

**编译顺序说明**：
1. `xdz-dependencies` → `xdz-framework`
2. 所有 API 模块可并行编译（无相互依赖）
3. Server 模块需要等待对应的 API 模块编译完成
   - `user-server` 需要 `user-api` 和 `business-api`
   - `vehicle-server` 需要 `vehicle-api`、`user-api`、`message-api`
   - `message-server` 需要 `message-api` 和 `vehicle-api`
   - `business-server` 需要所有 API 模块

### 服务间调用依赖关系（运行时 Feign 调用）

- **用户服务** (18080)
  - 调用：业务服务 API（短信验证码、社交登录等）
  
- **业务服务** (18081)
  - 调用：用户服务 API、车辆服务 API、消息服务 API
  - 包含：社区模块（帖子、评论、话题、敏感词管理等）
  
- **车辆服务** (18083)
  - 调用：用户服务 API、消息服务 API
  
- **消息服务** (18082)
  - 调用：车辆服务 API（接收车辆告警消息等）

## 🚀 启动步骤

### 1. 环境准备

#### 1.1 启动 MySQL
确保 MySQL 服务已启动，并创建相应的数据库。

#### 1.2 启动 Redis
```bash
# 启动 Redis（默认端口 6379）
redis-server
```

### 2. 数据库配置

根据各服务的 `application-local.yaml` 配置文件，修改数据库连接信息：

- **用户服务数据库**：`xdz_user`
- **车辆服务数据库**：`xdz_vehicle`
- **消息服务数据库**：`xdz_message`
- **业务服务数据库**：`xdz_business`（包含社区模块的表）
  - 社区模块的表位于 `xdz_business` 数据库中
  - 表名以 `community_` 开头（如 `community_post`、`community_comment` 等）

### 3. 编译项目

**重要**：首次启动前，必须先编译整个项目。Maven 会按照模块依赖顺序自动编译。

#### 编译顺序说明

由于模块之间存在依赖关系，必须按照以下顺序编译：

1. **xdz-dependencies**（依赖管理模块）- 提供版本管理
2. **xdz-framework**（框架基础模块）- 依赖 xdz-dependencies
3. **所有 API 模块**（可并行编译，无相互依赖）
   - xdz-module-user-api
   - xdz-module-vehicle-api
   - xdz-module-message-api
   - xdz-module-business-api
4. **Server 模块**（依赖对应的 API 模块）
   - xdz-module-user-server（依赖 user-api, business-api）
   - xdz-module-vehicle-server（依赖 vehicle-api, user-api, message-api）
   - xdz-module-message-server（依赖 message-api, vehicle-api）
   - xdz-module-business-server（依赖所有 API 模块）

#### 方式一：编译整个项目（推荐）

```bash
# 进入项目根目录
cd xdz_server

# 编译整个项目（Maven 会自动处理依赖顺序）
# 注意：使用 -DskipTests 跳过测试（测试代码已忽略，不提交到 Git）
mvn clean install -DskipTests
```

**说明**：
- Maven 会根据模块依赖关系自动确定编译顺序，无需手动指定
- 使用 `-DskipTests` 跳过测试阶段（测试代码不提交到 Git，本地也没有测试代码）
- 如果本地有测试代码想运行，可以不加 `-DskipTests` 参数

#### 方式二：分步编译（如果方式一失败或需要增量编译）

```bash
# 注意：所有命令都添加了 -DskipTests 参数跳过测试

# 1. 先编译依赖管理模块
mvn clean install -pl xdz-dependencies -am -DskipTests

# 2. 编译框架模块（依赖 xdz-dependencies）
mvn clean install -pl xdz-framework -am -DskipTests

# 3. 编译所有 API 模块（可并行，无相互依赖）
mvn clean install -pl xdz-module-user/xdz-module-user-api -am -DskipTests
mvn clean install -pl xdz-module-vehicle/xdz-module-vehicle-api -am -DskipTests
mvn clean install -pl xdz-module-message/xdz-module-message-api -am -DskipTests
mvn clean install -pl xdz-module-business/xdz-module-business-api -am -DskipTests

# 4. 编译用户服务（依赖 user-api, business-api）
mvn clean install -pl xdz-module-user -am -DskipTests

# 5. 编译车辆服务（依赖 vehicle-api, user-api, message-api）
mvn clean install -pl xdz-module-vehicle -am -DskipTests

# 6. 编译消息服务（依赖 message-api, vehicle-api）
mvn clean install -pl xdz-module-message -am -DskipTests

# 7. 编译业务服务（依赖所有 API 模块）
mvn clean install -pl xdz-module-business -am -DskipTests
```

**注意**：
- 如果编译失败，检查错误信息，通常是因为依赖模块未安装
- 如果某个服务模块修改了 API，需要重新编译该 API 模块，然后重新编译依赖它的 Server 模块
- 例如：修改了 `user-api`，需要重新编译 `xdz-module-user-api`，然后重新编译 `xdz-module-user-server` 和 `xdz-module-business-server`

### 4. 启动服务

#### 方式一：使用 Maven 启动（推荐）

**前提**：确保已完成步骤 3 的编译。

**启动用户服务**：
```bash
# 在项目根目录执行
cd xdz-module-user/xdz-module-user-server
mvn spring-boot:run -Dspring-boot.run.profiles=local -DskipTests
```

**启动业务服务**：
```bash
cd xdz-module-business/xdz-module-business-server
mvn spring-boot:run -Dspring-boot.run.profiles=local -DskipTests
```

**启动车辆服务**：
```bash
cd xdz-module-vehicle/xdz-module-vehicle-server
mvn spring-boot:run -Dspring-boot.run.profiles=local -DskipTests
```

**启动消息服务**：
```bash
cd xdz-module-message/xdz-module-message-server
mvn spring-boot:run -Dspring-boot.run.profiles=local -DskipTests
```

**说明**：
- 使用 `mvn spring-boot:run` 时，Maven 会自动编译依赖的模块
- 为了确保所有模块都已正确编译，建议先执行 `mvn clean install -DskipTests`
- 添加 `-DskipTests` 参数跳过测试（测试代码不提交到 Git）

#### 方式二：使用 IDE 启动

1. 在 IntelliJ IDEA 中打开项目
2. 找到各服务的启动类：
   - `UserServerApplication` - 用户服务
   - `BusinessServerApplication` - 业务服务
   - `VehicleServerApplication` - 车辆服务
   - `MessageServiceApplication` - 消息服务
3. 右键选择 `Run`，并设置 Active profiles 为 `local`

### 5. 启动顺序

**重要**：由于服务间存在依赖关系，必须按照以下顺序启动：

#### 推荐启动顺序

1. **用户服务**（18080）
   - 提供用户认证和 Token 生成
   - 提供用户服务 API（供业务服务调用）
   - **必须先启动**，因为业务服务依赖用户服务 API

2. **业务服务**（18081）
   - 提供系统管理功能（权限、角色、菜单等）
   - **包含社区模块**（帖子、评论、话题、敏感词管理等）
   - 依赖：用户服务 API、车辆服务 API、消息服务 API
   - **必须在用户服务启动后启动**

3. **车辆服务**（18083）
   - 提供车辆管理功能
   - 独立服务，可与其他服务并行启动

4. **消息服务**（18082）
   - 提供 SocketIO 实时通信
   - 独立服务，可与其他服务并行启动

#### 启动顺序说明

- **用户服务** 和 **业务服务** 存在相互依赖：
  - 用户服务调用业务服务 API（短信验证码、社交登录等）
  - 业务服务调用用户服务 API（用户信息查询等）
  - 建议先启动用户服务，再启动业务服务（或先启动业务服务，再启动用户服务，但需要处理启动时的调用失败）
  
- **车辆服务** 依赖用户服务 API 和消息服务 API：
  - 建议在用户服务启动后启动
  - 可以与消息服务并行启动
  
- **消息服务** 依赖车辆服务 API：
  - 建议在车辆服务启动后启动，或与车辆服务并行启动（如果消息服务启动时车辆服务未就绪，相关功能会暂时不可用）

- **业务服务** 包含社区模块，社区功能通过业务服务访问（端口 18081）

## 🌐 服务端口说明

| 服务 | 端口 | 说明 |
|------|------|------|
| 用户服务 | 18080 | 用户认证、会员管理、C端用户管理 |
| 业务服务 | 18081 | 系统管理、权限管理、**社区模块**（帖子、评论、话题、敏感词等） |
| 消息服务 | 18082 | SocketIO 实时通信 |
| 车辆服务 | 18083 | 车辆管理、车辆控制 |
| SocketIO | 9090 | WebSocket 实时通信端口 |

**注意**：社区模块已集成到业务服务中，通过业务服务的端口（18081）访问，路径为 `/admin-api/community/*`。

## ✅ 验证启动

### 检查服务是否启动成功

1. **用户服务**：访问 `http://localhost:18080`
2. **业务服务**：访问 `http://localhost:18081`
3. **车辆服务**：访问 `http://localhost:18083`
4. **消息服务**：访问 `http://localhost:18082`

### 查看日志

各服务的日志会输出到控制台，启动成功后会看到类似信息：

```
Started UserServerApplication in X.XXX seconds
Started BusinessServerApplication in X.XXX seconds
Started VehicleServerApplication in X.XXX seconds
Started MessageServiceApplication in X.XXX seconds
```

## 🔐 服务间调用说明

### 服务间 JWT Token

各服务之间通过 Feign 调用时，会自动生成服务间 JWT Token 进行认证。

**需要私钥的服务**（需要调用其他服务）：
- ✅ 用户服务 - 调用业务服务（短信验证码、社交登录等）
- ✅ 业务服务 - 调用车辆服务、消息服务
- ✅ 消息服务 - 调用车辆服务
- ✅ 车辆服务 - 可能调用用户服务、消息服务

**只需公钥的服务**（只被调用）：
- 所有服务都需要公钥来验证服务间 JWT Token

### 密钥文件位置

各服务的密钥文件位于：
```
xdz-module-{service}-server/src/main/resources/jwt/
├── service_jwt_private_key.pem  # 私钥（用于生成 Token）
└── service_jwt_public_key.pem   # 公钥（用于验证 Token）
```

## 🐛 常见问题

### 1. 编译失败：找不到 xdz-dependencies

**解决方案**：
```bash
mvn clean install -pl xdz-dependencies -am
```

### 2. 端口被占用

**解决方案**：修改 `application.yaml` 中的 `server.port` 配置

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

**解决方案**：检查 `application-local.yaml` 中的数据库配置：
- 数据库地址
- 数据库名称
- 用户名和密码

### 4. Redis 连接失败

**解决方案**：
- 确保 Redis 服务已启动
- 检查 `application-local.yaml` 中的 Redis 配置
- 默认端口：6379

### 5. 服务间调用失败

**解决方案**：
- 检查服务是否都已启动（特别是被依赖的服务）
- 检查服务间 JWT 密钥文件是否存在
- 查看日志中的错误信息
- 确认服务启动顺序是否正确（用户服务应先于业务服务启动）

### 6. 社区模块接口返回 404

**解决方案**：
- 确认业务服务已启动（社区模块集成在业务服务中）
- 检查接口路径是否正确：`/admin-api/community/*`
- 确认数据库表已创建（社区模块的表在 `xdz_business` 数据库中）
- 检查是否有 Bean 名称冲突（已通过重命名解决：`CommunityPostMapper`、`CommunityTopicMapper` 等）

## 📝 配置文件说明

各服务的配置文件位于：
```
xdz-module-{service}-server/src/main/resources/
├── application.yaml           # 主配置文件
├── application-local.yaml     # 本地开发环境配置
├── application-dev.yaml       # 开发环境配置
└── application-prod.yaml      # 生产环境配置
```

启动时使用 `local` profile，会加载 `application.yaml` 和 `application-local.yaml`。

## 🔗 相关链接

- Spring Boot 官方文档：https://spring.io/projects/spring-boot
- 项目 Git 仓库：[Git 地址]

## 📞 技术支持

如有问题，请联系开发团队。