# 系统架构设计

## 🏗️ 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                          Browser (Vue Web)                    │
│                      http://localhost:5173                    │
└────────────────────────┬────────────────────────────────────┘
                         │
                    HTTP Requests
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   API Gateway (Spring Cloud)                  │
│              http://localhost:8080 (Port 8080)               │
│                                                               │
│  Functions:                                                   │
│  • Route requests to backend services                        │
│  • Record request entry point logs                          │
│  • Apply global interceptors                                │
└────────┬──────────────────────┬──────────────────────┬────────┘
         │                      │                      │
    /order/*              /payment/*              /health
         │                      │                      │
         ▼                      ▼                      ▼
    ┌─────────────┐      ┌──────────────┐      ┌──────────────┐
    │Order Service │      │Payment Service│      └──────────────┘
    │(Port 8081)  │      │(Port 8082)    │
    │             │      │               │
    │ /order/     │      │ /payment/     │
    │  ├─ create  │      │  ├─ pay       │
    │  ├─ delete  │      │  ├─ refund    │
    │  ├─ get     │      │  └─ get       │
    │  └─ pay     │      │               │
    └─────────────┘      └──────────────┘
```

## 📦 模块设计

### 1. shop-recycle-common (公共模块)

**职责:** 提供日志、配置、DTO等公共能力

**包含:**
- `LoggingMdcInterceptor` - 日志MDC拦截器
- `Response<T>` - 统一响应类
- `WebConfig` - Web配置（注册拦截器）

**关键特性:**
```
自动填充MDC字段:
  ✓ traceId    (链路追踪ID)
  ✓ uri        (原始请求路径)
  ✓ uri_group  (规范化URI分组)
  ✓ event_class (事件分类)
  ✓ duration   (请求耗时)
  ✓ status     (HTTP状态)
  ✓ error      (错误堆栈)
```

### 2. shop-recycle-gateway (API网关)

**职责:** 请求路由、负载均衡、协议转换

**配置:**
```yaml
routes:
  - id: order-service
    uri: http://localhost:8081    # 本地开发
    条件: Path=/api/order/**

  - id: payment-service
    uri: http://localhost:8082
    条件: Path=/api/payment/**
```

**日志链路:**
```
浏览器请求 → Gateway (日志记录进入点)
         → 路由转发 → Order Service
         → 生成响应 → 返回浏览器
```

### 3. shop-recycle-order-service (订单服务)

**职责:** 订单CRUD操作

**数据模型:**
```java
OrderResponse {
  orderId      // ORD-XXXXX (自动生成)
  userId       // 用户ID (来自请求头)
  price        // 订单金额
  status       // CREATED, PAID, CANCELLED
  description  // 订单描述
  createdAt    // 创建时间戳
}
```

**业务逻辑:**
```java
✓ createOrder()     - 创建订单 (校验价格>0)
✓ deleteOrder()     - 删除订单 (已支付的不能删除)
✓ getOrder()        - 查询订单
✓ updateOrderStatus() - 更新状态 (订单支付时调用)
```

**日志埋点:**
```
DEBUG: 订单创建逻辑开始
INFO:  订单已创建 orderId=ORD-XXXXX
WARN:  订单不存在 orderId=...
ERROR: 订单创建失败 (异常堆栈)
```

### 4. shop-recycle-payment-service (支付服务)

**职责:** 订单支付、退款

**数据模型:**
```java
PaymentResponse {
  paymentId       // PAY-XXXXX (自动生成)
  orderId         // 关联的订单
  amount          // 支付金额
  status          // PENDING, SUCCESS, FAILED, REFUNDED
  paymentMethod   // CARD, WECHAT, ALIPAY
  paidAt          // 支付时间戳
}
```

**业务逻辑:**
```java
✓ payOrder()   - 支付订单 (模拟30%失败率)
✓ refund()     - 退款 (仅成功支付可退,模拟10%失败率)
✓ getPayment() - 查询支付
```

**日志埋点:**
```
DEBUG: 订单支付逻辑开始
INFO:  订单支付成功 paymentId=PAY-XXXXX
WARN:  支付金额不合法
ERROR: 第三方支付失败 (异常堆栈)
```

### 5. shop-recycle-web (Vue前端)

**职责:** 提供Web UI，调用API生成测试流量

**技术栈:**
- Vue 3 (创意性组件框架)
- Vite (构建工具)
- Axios (HTTP客户端)

**页面组件:**
- **OrderComponent** - 订单管理界面
- **PaymentComponent** - 支付管理界面

**代理配置 (vite.config.js):**
```javascript
proxy: {
  '/api': {
    target: 'http://localhost:8080',  // API Gateway
    changeOrigin: true
  }
}
```

## 🔄 请求流程示例

### 完整的订单创建流程

```
Step 1: 用户提交表单
浏览器 → POST /api/order/create
         ↓
Step 2: Gateway接收请求
Gateway → LoggingMdcInterceptor (记录进入点)
         ├─ traceId = UUID生成
         ├─ uri = /api/order/create
         ├─ uri_group = /order/*
         └─ event_class = order
         ↓
Step 3: 路由转发到Order Service
Gateway → Order Service (http://localhost:8081/api/order/create)
         ↓
Step 4: Order Service处理请求
Order Service → OrderController.createOrder()
              → OrderService.createOrder()
              → generate orderId
              → save to memory
              → MDC.put("status", "success")
              └─ log.info("订单已创建")
         ↓
Step 5: 响应返回
Order Service → Response.success({orderId, userId, ...})
              ↓
Step 6: 前端接收响应
浏览器 ← {code: 0, msg: "success", data: {...}}
       └─ Display success message
```

### 后端日志输出

```json
[Gateway在处理请求时]
{
  "ts":"2024-02-06T10:30:45.123Z",
  "app":"shop-recycle-gateway",
  "uri":"/api/order/create",
  "uri_group":"/order/*",
  "traceId":"550e8400-e29b-41d4-a716-446655440000"
}

[Order Service处理业务逻辑时]
{
  "ts":"2024-02-06T10:30:45.200Z",
  "app":"shop-recycle-order-service",
  "level":"INFO",
  "msg":"订单已创建 orderId=ORD-A1B2C3D4",
  "event_class":"order",
  "status":"success",
  "duration":"156",  // 毫秒
  "traceId":"550e8400-e29b-41d4-a716-446655440000"
}
```

## 📊 日志字段映射表

| MDC字段 | 来源 | 设置位置 | 备注 |
|---------|------|---------|------|
| `traceId` | 请求头或生成 | Interceptor.preHandle() | X-B3-TraceId或UUID生成 |
| `uri` | HttpRequest | Interceptor.preHandle() | 原始请求路径 |
| `uri_group` | 规范化逻辑 | normalizeUri() | /order/* /payment/* |
| `event_class` | 规则匹配 | deriveEventClass() | order/payment/auth/api |
| `userId` | 请求头 | Interceptor.preHandle() | X-User-Id头 |
| `start_time` | System.time | Interceptor.preHandle() | 用于后续计算duration |
| `duration` | 计算得出 | Interceptor.afterCompletion() | 当前时间 - start_time |
| `error` | 异常/状态码 | Interceptor.afterCompletion() | Exception.toString()或HTTP状态 |
| `status` | HTTP状态码 | Interceptor.afterCompletion() | success/client_error/server_error |

## 🔑 关键设计决策

### 1. 拦截器而不是过滤器
```
✓ 优点: 可以访问Handler和ModelMap
✓ 优点: 在业务方法执行前后进行处理
✓ 适合: 日志、权限、性能监控
```

### 2. 异步Appender
```
✓ 优点: 异步输出日志，不阻塞业务线程
✓ 优点: 可配置队列大小和丢弃策略
✓ 配置: AsyncAppender + queueSize=1024
```

### 3. JSON格式日志
```
✓ 优点: 可被Loki/ELK直接解析
✓ 优点: 支持结构化查询
✓ 工具: LogstashEncoder
```

### 4. MDC而不是参数传递
```
✓ 优点: 零侵入，业务代码无需改动
✓ 优点: 自动在线程本地存储
✓ 优点: 所有日志自动包含上下文
```

### 5. URI规范化
```
✓ 原始: /order/create /order/12345/delete /order/abc/pay
✓ 规范化: /order/* (减少基数)
✓ 好处: Prometheus label基数可控
```

## 🌐 环境配置

### 本地开发 (local)
```yaml
Gateway:
  order-service: http://localhost:8081
  payment-service: http://localhost:8082

Frontend:
  Vite proxy: http://localhost:8080
```

### Docker容器 (docker)
```yaml
Gateway:
  order-service: http://order-service:8081   (DNS名称)
  payment-service: http://payment-service:8082

Network:
  All services connected via app-network bridge
```

### 生产环境 (prod - 示例)
```yaml
Gateway:
  order-service: http://order-service.default.svc.cluster.local:8081
  payment-service: http://payment-service.default.svc.cluster.local:8082

Log aggregation:
  Vector agent → Loki endpoint
  Prometheus scrape: /actuator/prometheus
```

## 📈 可观测性支持

### 日志可观测 (Structured Logging)
```
✓ Fields: traceId, uri_group, event_class, duration, status
✓ Format: JSON (parseable)
✓ Tool: Loki/ELK for Log aggregation
```

### 指标可观测 (Metrics)
```
✓ Requests total (按uri_group分组)
✓ Requests errors
✓ Request duration (直方图)
✓ Order/Payment specific counters
Tool: Prometheus + Vector for export
```

### 链路可观测 (Tracing)
```
✓ traceId: 记录在每个日志中
✓ X-B3-TraceId: 支持Jaeger/Zipkin集成
✓ 可通过traceId查询完整链路
```

## 🔬 测试架构

### 单元测试
```
service层 → 业务逻辑 (MockOrderService)
```

### 集成测试
```
Controller → Service → 内存DB (实际执行)
```

### 端到端测试
```
Vue前端 → API Gateway → Order Service → Payment Service
         (完整的HTTP链路)
```

使用QUICK_START.md中的测试脚本进行E2E测试。

---

**相关文档:**
- [QUICK_START.md](QUICK_START.md) - 快速开始
- [API.md](API.md) - API详细文档
- [README.md](README.md) - 项目文档