# 双应用架构文档

## 架构概述

本项目采用双应用架构，将客户端应用和后台管理应用分离，通过网关统一路由，实现独立部署和运维。

## 架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                     客户端/浏览器                         │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
              ┌─────────────────┐
              │    Gateway     │  8080
              │   (网关)       │
              └────────┬────────┘
                       │
          ┌────────────┴────────────┐
          │                         │
          ▼                         ▼
┌──────────────────┐      ┌──────────────────┐
│  Client App     │      │  Admin App      │  8082
│   (客户端应用)   │      │  (后台管理应用)  │
│     8081       │      │                 │
└────────┬─────────┘      └────────┬─────────┘
         │                        │
         └────────────┬───────────┘
                      │
                      ▼
              ┌─────────────────┐
              │  PostgreSQL     │
              │   (数据库)       │
              └─────────────────┘
```

## 模块说明

### 1. 网关模块 (everything-is-suitable-gateway)
- **端口**: 8080
- **职责**: 
  - 统一入口，路由请求到对应的应用
  - JWT 认证和 RBAC 权限验证
  - 负载均衡和熔断降级
- **路由规则**:
  - `/api/client/**` → Client App (8081)
  - `/api/admin/**` → Admin App (8082)
  - `/api/auth/**` → Client App (8081)
  - `/api/fortune/**` → Client App (8081)

### 2. 客户端应用 (everything-is-suitable-client-app)
- **端口**: 8081
- **职责**:
  - 处理客户端用户请求
  - 提供命理查询服务
  - 用户认证和授权
- **依赖**:
  - everything-is-suitable-client-api (接口层)
  - everything-is-suitable-biz (业务逻辑)
  - everything-is-suitable-common (公共组件)

### 3. 后台管理应用 (everything-is-suitable-admin-app)
- **端口**: 8082
- **职责**:
  - 处理后台管理请求
  - 用户管理和权限控制
  - 统计数据查询
- **依赖**:
  - everything-is-suitable-admin-api (接口层)
  - everything-is-suitable-sys (系统管理)
  - everything-is-suitable-statistics (统计分析)

### 4. 客户端接口层 (everything-is-suitable-client-api)
- **职责**:
  - 定义客户端 API 路由
  - 实现 Handler 处理请求
  - 参数验证和响应封装

### 5. 后台管理接口层 (everything-is-suitable-admin-api)
- **职责**:
  - 定义后台管理 API 路由
  - 实现 Handler 处理请求
  - RBAC 权限控制

### 6. 公共模块 (everything-is-suitable-common)
- **职责**:
  - 提供通用工具类
  - JWT 认证工具类
  - JWT 认证过滤器
  - RBAC 权限过滤器

### 7. 业务模块 (everything-is-suitable-biz)
- **职责**:
  - 命理分析业务逻辑
  - 数据访问层
  - 业务规则实现

## 认证和授权

### JWT 认证
- **实现**: `JwtTokenProvider`
- **功能**:
  - 生成 JWT Token
  - 验证 JWT Token
  - 解析 JWT Token
- **过滤器**: `JwtAuthenticationFilter`
  - 自动提取和验证 JWT Token
  - 将用户信息添加到请求头

### RBAC 权限控制
- **实现**: `RbacAuthorizationFilter`
- **角色定义**:
  - **ADMIN**: 管理员，拥有所有权限
  - **MANAGER**: 经理，拥有读取权限
  - **OPERATOR**: 操作员，拥有基础权限
- **权限映射**:
  - `users:read`, `users:write`, `users:delete`
  - `statistics:read`
  - `fortune:read`, `fortune:write`
  - `settings:read`, `settings:write`

## 缓存策略

### Caffeine 本地缓存
- **用户信息**: 缓存 5 分钟
- **命理结果**: 缓存 10 分钟
- **统计数据**: 缓存 1 分钟
- **配置**:
  ```yaml
  spring:
    cache:
      type: caffeine
      caffeine:
        spec: maximumSize=1000,expireAfterWrite=5m
  ```

## 部署方案

### Docker 部署
- **容器化**: 所有应用使用 Docker 容器部署
- **编排**: 使用 Docker Compose 编排服务
- **网络**: 使用 bridge 网络连接服务

### 部署命令
```bash
# 构建和部署
./build-and-deploy.sh

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

# 使用 Docker Compose
docker-compose up -d
docker-compose down
```

### 环境变量
- `JWT_SECRET`: JWT 密钥
- `JWT_EXPIRATION`: JWT 过期时间
- `SPRING_PROFILES_ACTIVE`: Spring Profile
- `SPRING_DATASOURCE_URL`: 数据库连接 URL
- `SPRING_DATASOURCE_USERNAME`: 数据库用户名
- `SPRING_DATASOURCE_PASSWORD`: 数据库密码

## 监控和运维

### Actuator 端点
- `/actuator/health`: 健康检查
- `/actuator/metrics`: 性能指标
- `/actuator/prometheus`: Prometheus 指标

### 日志管理
- 使用 SLF4J + Logback
- 日志级别可配置
- 支持结构化日志输出

## 性能优化

### JVM 优化
- 堆内存: `-Xms512m -Xmx1024m`
- GC 策略: `-XX:+UseG1GC -XX:MaxGCPauseMillis=200`
- 其他优化: `-XX:+UseStringDeduplication`

### 数据库优化
- 连接池配置
- 查询优化和索引
- 使用 R2DBC 非阻塞访问

### 响应式优化
- 使用 WebFlux 非阻塞特性
- 背压处理
- 避免阻塞操作

## 安全考虑

### 认证安全
- JWT Token 过期机制
- Token 刷新机制
- 密钥安全管理

### 授权安全
- RBAC 权限控制
- 路径级别的权限验证
- HTTP 方法级别的权限控制

### 数据安全
- 敏感数据加密
- SQL 注入防护
- XSS 防护

## 扩展性

### 水平扩展
- 可独立扩展客户端应用
- 可独立扩展后台管理应用
- 网关支持负载均衡

### 垂直扩展
- 增加 JVM 堆内存
- 优化数据库连接池
- 增加缓存容量

## 迁移指南

### 从单体应用迁移
1. 创建新的应用模块
2. 迁移 Handler 到接口层
3. 配置网关路由
4. 更新客户端调用地址
5. 验证功能完整性
6. 逐步切换流量

### 数据迁移
- 数据库结构保持不变
- 共享数据库连接
- 使用 Flyway 管理迁移

## 故障排查

### 常见问题
1. **网关无法连接后端服务**
   - 检查服务是否启动
   - 检查网络连接
   - 检查端口配置

2. **JWT 认证失败**
   - 检查 JWT 密钥配置
   - 检查 Token 过期时间
   - 检查 Token 格式

3. **权限验证失败**
   - 检查角色配置
   - 检查权限映射
   - 检查请求头传递

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

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

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

## 总结

双应用架构通过分离客户端和后台管理应用，实现了：
- ✅ 独立部署和运维
- ✅ 灵活的扩展能力
- ✅ 统一的认证和授权
- ✅ 高性能的响应式架构
- ✅ 完善的监控和日志