feat: initialize Gradle multi-module backend and Vite frontend

2026-08-06 17:17:44 +08:00
commit 2cf32d0768
52 changed files with 2970 additions and 0 deletions
@@ -0,0 +1,79 @@
+# 开发指南
+
+本文档说明如何在本地搭建并运行 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。改端口见上表。