# 开发指南

本文档说明如何在本地搭建并运行 im-system。

## 环境要求

- **JDK 21**（后端 toolchain 锁定；需本机安装，或由 Gradle 自动下载）
- **Gradle 9.6+**（仅首次生成 wrapper 需要）
- **Node.js 20.19+**
- **pnpm 11+**
- **Kafka**（可选，见下文）

## 后端

### 首次初始化

仓库不含 Gradle wrapper，首次需用本机 Gradle 生成（生成后应 commit 进仓库）：

```bash
cd backend
gradle wrapper --gradle-version 9.6.1
```

之后一律使用 `./gradlew`，不再依赖本机 Gradle。

### 启动三个服务

```bash
cd backend
./gradlew :gateway:bootRun      # 网关，http://localhost:8080
./gradlew :im-service:bootRun   # 主服务，http://localhost:8081
./gradlew :log-service:bootRun  # 日志服务，http://localhost:8082
```

- 三个服务需分终端启动（或加 `&` 后台运行）。
- 依赖 Kafka 的功能（im-service 发日志 → log-service 消费）需先启动 Kafka；只跑网关转发可暂不起 Kafka。

## 前端

```bash
cd frontend
pnpm install
```

### 启动

```bash
pnpm --filter @im-system/admin dev    # 管理后台，http://localhost:5173
pnpm --filter @im-system/app dev      # 聊天 App，http://localhost:1420
```

### 构建与检查

```bash
pnpm -r build          # 全量构建
pnpm type-check        # 全量类型检查
```

## 服务通信

- **Gateway** 统一入口与路由：`/api/im/**` → im-service，`/api/log/**` → log-service。
- **im-service** 通过 Kafka 向 topic `im-logs` 发送日志消息。
- **log-service** 监听同一 topic（consumer group `log-service`）消费并落库。
- 前端 dev 阶段：admin 的 `/api` 代理到 `localhost:8080`（gateway）；app 直连后端地址。

## 配置项

| 项目 | 位置 | 默认值 |
| --- | --- | --- |
| Kafka 地址 | 各服务 `application.yml` 的 `KAFKA_BOOTSTRAP_SERVERS` | `localhost:9092` |
| 后端端口 | 各 `application.yml` 的 `server.port` | 8080 / 8081 / 8082 |
| 前端端口 | 各 `vite.config.ts` 的 `server.port` | 5173 / 1420 |
| gateway 路由 | `gateway/src/main/resources/application.yml` 的 `spring.cloud.gateway.routes` | `/api/im/**`、`/api/log/**` |

## 常见问题

- **Gradle `Unresolved reference`**：每个子项目脚本需独立声明 `plugins {}`，根脚本只集中钉版本（`apply false`）。避免在根 `subprojects {}` 里用 `apply(plugin=...)` + 静态访问器（`implementation`、`kotlin` 等），否则脚本编译期无法解析。
- **Kafka 连接失败**：确认 Kafka 已启动，`bootstrap-servers` 正确（默认 `localhost:9092`）。
- **端口占用**：8080/8081/8082、5173、1420。改端口见上表。