XuqmGroup-Server/CLAUDE.md

# XuqmGroup-Server — Claude 项目上下文

## 项目定位

XuqmGroup 后端服务集合。Spring Boot 3.4.4 + Java 21 + Maven 多模块微服务架构。

- Git 远端：`https://xuqinmin.com/xuqmGroup/XuqmGroup-Server.git`
- 技术栈：Spring Boot 3.4.4，Java 21，Spring Security 6（JWT），Spring Data JPA，MySQL 8，Redis 7

## 模块结构

```
XuqmGroup-Server/
├── pom.xml              # 父 POM，统一依赖版本
├── common/              # 公共库（ApiResponse、JWT、异常处理）
├── tenant-service/      # 租户服务      :8081
├── im-service/          # IM 服务       :8082
├── push-service/        # 推送服务      :8083
├── update-service/      # 版本管理服务  :8084
├── license-service/     # 证书授权服务  :8085
├── file-service/        # 文件服务
├── im-sdk/              # IM SDK（服务端封装）
├── xuqm-bugcollect-service/  # Bug 收集服务  :9006
└── demo-service/        # 演示服务
```

## 服务端口

| 服务 | 端口 | 说明 |
|------|------|------|
| tenant-service | 8081 | 租户管理、认证、应用管理 |
| im-service | 8082 | IM 消息、群组、WebSocket |
| push-service | 8083 | 推送 token 注册、推送发送 |
| update-service | 8084 | App/RN Bundle 版本管理 |
| license-service | 8085 | 证书授权 |
| xuqm-bugcollect-service | 9006 | Bug 收集、错误追踪、漏斗分析 |

## 技术栈

| 组件 | 版本 |
|------|------|
| Spring Boot | 3.4.4 |
| Java | 21 |
| Spring Security | 6.x（JWT 无状态认证） |
| Spring Data JPA | Hibernate 6 |
| MySQL | 8.x |
| Redis | 7.x |
| JJWT | 0.12.6 |
| Spring WebSocket + STOMP | IM 实时通信 |

## 快速启动

```bash
# 前置：MySQL 8 + Redis 7 本地运行
cd XuqmGroup-Server

# 启动所有服务
cd tenant-service && mvn spring-boot:run &
cd im-service     && mvn spring-boot:run &
cd push-service   && mvn spring-boot:run &
cd update-service && mvn spring-boot:run &
cd xuqm-bugcollect-service && mvn spring-boot:run &
```

首次启动自动建表（ddl-auto: update）。  
默认管理员：`admin` / `Admin@123456`

## 核心 API 概览

### tenant-service（:8081）

- 认证：`/api/auth/login`、`/api/auth/register`、`/api/auth/captcha`
- 应用管理：`/api/apps` CRUD
- 功能服务：`/api/apps/{appKey}/services`（IM/Push/Update 开关）
- 子账号：`/api/sub-accounts`
- 运营平台：`/api/ops/tenants`、`/api/ops/statistics`

### im-service（:8082）

- 消息：`/api/im/messages/send`、`/api/im/messages/history/{toId}`
- 群组：`/api/im/groups` CRUD
- WebSocket：`ws://localhost:8082/ws/im?token=<jwt>`
- 关键词过滤、Webhook

### push-service（:8083）

- Token：`/api/push/register`、`/api/push/device/unregister`
- 推送：`/api/push/send`、`/api/push/internal/notify`
- 开关：`/api/push/receive-push`

### update-service（:8084）

- App 更新：`/api/v1/updates/app/check`、`/api/v1/updates/app/upload`
- RN Bundle：`/api/v1/rn/update/check`、`/api/v1/rn/upload`

### xuqm-bugcollect-service（:9006）

Bug 收集、错误去重、SourceMap 符号化、Webhook 通知、漏斗分析。

- 核心 API 前缀：`/bugcollect/v1/`
- 使用 Flyway 管理数据库迁移
- tenant-service 的 `/api/sdk/config` 已返回 `bugCollectApiUrl`、`bugCollectEnabled` 字段

## 常用命令

```bash
mvn spring-boot:run -pl tenant-service    # 启动单个服务
mvn clean package                         # 打包所有模块
mvn clean package -pl tenant-service      # 打包单个服务
```