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-log-service/    # 日志服务      :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-log-service	9006	日志收集、错误追踪、漏斗分析

技术栈

组件	版本
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 实时通信

快速启动

# 前置：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-log-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-log-service（:9006）

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

• 核心 API 前缀：/log/v1/
• 使用 Flyway 管理数据库迁移
• tenant-service 的 /api/sdk/config 已返回 logApiUrl、logEnabled 字段

常用命令

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