# Everything Is Suitable API

基于 Spring Boot 3.x 和响应式编程的命理分析 API 系统，采用双应用架构设计。

## 项目概述

本项目是一个完整的命理分析服务平台，支持：
- 客户端用户命理查询
- 后台管理系统
- 用户认证和授权
- 数据统计分析

## 架构设计

### 双应用架构

项目采用双应用架构，将客户端应用和后台管理应用分离：

```
Gateway (8080) → Client App (8081)
              → Admin App (8082)
              → PostgreSQL
```

**优势**:
- 独立部署和运维
- 灵活的扩展能力
- 统一的认证和授权
- 高性能的响应式架构

### 技术栈

- **框架**: Spring Boot 3.5.10
- **响应式**: Spring WebFlux + R2DBC
- **网关**: Spring Cloud Gateway
- **认证**: JWT
- **授权**: RBAC
- **缓存**: Caffeine
- **数据库**: PostgreSQL 16
- **容器化**: Docker + Docker Compose

## 模块说明

### 应用模块
- `everything-is-suitable-client-app`: 客户端应用 (8081)
- `everything-is-suitable-admin-app`: 后台管理应用 (8082)
- `everything-is-suitable-gateway`: 网关 (8080)

### 接口层模块
- `everything-is-suitable-client-api`: 客户端接口层
- `everything-is-suitable-admin-api`: 后台管理接口层

### 业务模块
- `everything-is-suitable-biz`: 命理分析业务逻辑
- `everything-is-suitable-client`: 客户端核心功能
- `everything-is-suitable-sys`: 系统管理
- `everything-is-suitable-statistics`: 统计分析

### 公共模块
- `everything-is-suitable-common`: 公共组件和工具类
- `everything-is-suitable-db`: 数据库访问层

## 快速开始

### 前置要求

- JDK 21+
- Maven 3.8+
- Docker 20.10+
- Docker Compose 2.0+

### 本地开发

```bash
# 克隆项目
git clone <repository-url>
cd everything-is-suitable-api

# 编译项目
mvn clean install

# 启动服务
mvn spring-boot:run -pl everything-is-suitable-gateway
```

### Docker 部署

```bash
# 构建和部署所有服务
./build-and-deploy.sh

# 停止所有服务
./stop-services.sh

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f
```

## API 端点

### 网关端点
- `http://localhost:8080/api/auth/login`: 用户登录
- `http://localhost:8080/api/auth/register`: 用户注册
- `http://localhost:8080/api/fortune/daily`: 每日命理
- `http://localhost:8080/api/fortune/monthly`: 每月命理
- `http://localhost:8080/api/fortune/yearly`: 每年命理

### 后台管理端点
- `http://localhost:8080/api/admin/users`: 用户管理
- `http://localhost:8080/api/admin/statistics`: 统计数据

### 监控端点
- `http://localhost:8080/actuator/health`: 健康检查
- `http://localhost:8080/actuator/metrics`: 性能指标

## 认证和授权

### JWT 认证

所有需要认证的端点都需要在请求头中提供 JWT Token：

```bash
Authorization: Bearer <token>
```

### RBAC 权限

后台管理端点需要相应的权限：

| 角色 | 权限 |
|------|--------|
| ADMIN | 所有权限 |
| MANAGER | 读取权限 |
| OPERATOR | 基础权限 |

## 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|---------|
| JWT_SECRET | JWT 密钥 | this-is-a-secure-jwt-secret-key... |
| JWT_EXPIRATION | JWT 过期时间 (ms) | 86400000 |
| SPRING_PROFILES_ACTIVE | Spring Profile | dev |
| SPRING_DATASOURCE_URL | 数据库 URL | r2dbc:postgresql://localhost:5432/everything_is_suitable |
| SPRING_DATASOURCE_USERNAME | 数据库用户名 | postgres |
| SPRING_DATASOURCE_PASSWORD | 数据库密码 | postgres |

### Profile 配置

- `dev`: 开发环境
- `prod`: 生产环境

## 测试

### 运行测试

```bash
# 运行所有测试
mvn test

# 运行特定模块测试
mvn test -pl everything-is-suitable-common

# 运行特定测试类
mvn test -Dtest=JwtAuthenticationFilterTest
```

### 测试覆盖率

```bash
# 生成测试覆盖率报告
mvn jacoco:report

# 查看报告
open target/site/jacoco/index.html
```

## 性能优化

### JVM 优化

```bash
-Xms512m -Xmx1024m -XX:+UseG1GC -XX:MaxGCPauseMillis=200
```

### 缓存配置

```yaml
spring:
  cache:
    type: caffeine
    caffeine:
      spec: maximumSize=1000,expireAfterWrite=5m
```

详见 [性能测试和优化文档](./docs/performance-testing-and-optimization.md)

## 文档

- [双应用架构文档](./docs/dual-app-architecture.md)
- [性能测试和优化](./docs/performance-testing-and-optimization.md)
- [实施计划](./docs/plans/2025-02-24-dual-app-architecture-refactor.md)

## 开发规范

### 代码风格
- 遵循 Google Java Style Guide
- 使用 Checkstyle 进行代码检查
- 代码覆盖率要求 ≥ 80%

### Git 提交规范
```
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具链相关
```

## 故障排查

### 常见问题

1. **端口被占用**
   ```bash
   # 检查端口占用
   lsof -i :8080
   lsof -i :8081
   lsof -i :8082
   ```

2. **数据库连接失败**
   - 检查 PostgreSQL 是否启动
   - 检查数据库连接配置
   - 检查网络连接

3. **JWT 认证失败**
   - 检查 JWT_SECRET 配置
   - 检查 Token 格式
   - 检查 Token 过期时间

### 日志查看

```bash
# 查看网关日志
docker logs everything-is-suitable-gateway

# 查看客户端应用日志
docker logs everything-is-suitable-client-app

# 查看后台管理应用日志
docker logs everything-is-suitable-admin-app
```

## 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 联系方式

- 项目主页: [GitHub Repository]
- 问题反馈: [Issues]
- 文档: [Wiki]