# 快速开始指南

## 📌 前置要求

- **JDK 8+** (测试版本: JDK 1.8)
- **Maven 3.6+** 
- **Node.js 14+** 和 **npm**

## ⚡ 一句命令快速启动 (推荐)

在项目根目录运行：

```powershell
.\start.ps1
```

或 Linux/Mac:
```bash
chmod +x start.sh && ./start.sh
```

<br/>

## 🚀 30秒快速启动 (Windows PowerShell)

在项目根目录运行：

```powershell
.\start.ps1
```

或者手动启动：

### 方式1：Terminal分别启动3个服务

**Terminal 1 - API Gateway:**
```bash
cd spring-cloud-log-demo
mvn clean install
cd shop-recycle-gateway
mvn spring-boot:run
```

**Terminal 2 - Order Service:**
```bash
cd spring-cloud-log-demo/shop-recycle-order-service
mvn spring-boot:run
```

**Terminal 3 - Payment Service:**
```bash
cd spring-cloud-log-demo/shop-recycle-payment-service
mvn spring-boot:run
```

**Terminal 4 - Frontend:**
```bash
cd spring-cloud-log-demo/shop-recycle-web
npm install
npm run dev
```

## 🎯 核心工作流程

### Step 1: 访问前端界面
打开浏览器访问 **http://localhost:5173**

你会看到两个标签页：
- 📦 **订单管理**: 创建、删除订单
- 💰 **支付管理**: 支付订单、退款

### Step 2: 创建订单
在"订单管理"标签页中：
1. 输入 `用户ID`: user123
2. 输入 `订单金额`: 99.99
3. 输入 `描述`: test order
4. 点击 "创建订单" 按钮

**预期结果:**
- 页面显示 "订单创建成功!"
- Order Service Terminal会输出 JSON 格式的日志：
```json
{
  "ts":"2024-02-06T10:30:45.123Z",
  "level":"INFO",
  "msg":"订单已创建 orderId=ORD-XXXXX",
  "traceId":"550e8400-e29b-41d4-a716-446655440000",
  "uri":"/api/order/create",
  "uri_group":"/order/*",
  "event_class":"order",
  "status":"success",
  "duration":"145"
}
```

### Step 3: 支付订单
在"支付管理"标签页中：
1. 输入 `订单ID`: 复制上一步的 orderId
2. 输入 `金额`: 99.99
3. 选择 `支付方式`: 微信/支付宝/银行卡
4. 点击 "支付" 按钮

**预期结果:**
- 页面显示 "支付成功!" 或 "支付失败"
- Payment Service Terminal会输出支付相关的JSON日志
- **注意**: Payment Service有30%的失败率用于测试异常处理

### Step 4: 查看日志
观察三个服务的Terminal输出，你会看到：

**关键字段解析:**

| 字段 | 含义 | 示例 |
|------|------|------|
| `traceId` | 全链路追踪ID | `550e8400-e29b-41d4` |
| `uri_group` | 规范化URL分组 | `/order/*`, `/payment/*` |
| `event_class` | 业务事件分类 | `order`, `payment` |
| `duration` | 请求耗时(毫秒) | `145` |
| `status` | 请求状态 | `success`, `client_error`, `server_error` |
| `app` | 应用名 | `shop-recycle-order-service` |
| `env` | 环境 | `local` |

## � 无UI批量模拟 - URL API测试

**不想用UI？一行命令生成100条订单！**

### 快速命令示例

```bash
# 生成1条随机订单
curl http://localhost:8080/api/test/order

# 生成10条订单
curl http://localhost:8080/api/test/order/batch?count=10

# 生成50条订单
curl http://localhost:8080/api/test/order/batch?count=50

# 生成100条订单 (大量日志测试)
curl http://localhost:8080/api/test/order/batch?count=100

# 进行10秒压力测试，观察QPS
curl http://localhost:8080/api/test/order/stress?duration=10

# 生成10笔支付
curl http://localhost:8080/api/test/payment/batch?count=10

# 支付场景测试：支付 + 退款
curl "http://localhost:8080/api/test/payment/refund?count=5"
```

### 完整脚本示例 (快速生成大量日志)

```bash
#!/bin/bash
# save as: run-batch-test.sh

echo "🚀 开始批量生成模拟数据..."
echo ""

echo "📦 生成50个订单..."
curl -s http://localhost:8080/api/test/order/batch?count=50 | jq '.data | {total, success, error, duration}'
echo ""

echo "💰 生成30笔支付..."
curl -s http://localhost:8080/api/test/payment/batch?count=30 | jq '.data | {total, success, error, totalAmount, duration}'
echo ""

echo "📊 场景测试(10轮)..."
curl -s http://localhost:8080/api/test/order/scenario?count=10 | jq '.data'
echo ""

echo "⚡ 压力测试(10秒)..."
curl -s http://localhost:8080/api/test/order/stress?duration=10 | jq '.data | {requests, success, error, qps, duration}'
echo ""

echo "✅ 完成!现在检查后端Terminal的JSON日志输出"
```

运行:
```bash
chmod +x run-batch-test.sh
./run-batch-test.sh
```

### PowerShell 脚本 (Windows)

```powershell
# save as: run-batch-test.ps1

Write-Host "🚀 批量生成模拟数据" -ForegroundColor Cyan
Write-Host ""

Write-Host "📦 生成50个订单..." -ForegroundColor Yellow
(Invoke-WebRequest -Uri "http://localhost:8080/api/test/order/batch?count=50").Content | ConvertFrom-Json | ForEach-Object { $_.data }

Write-Host ""
Write-Host "💰 生成30笔支付..." -ForegroundColor Yellow  
(Invoke-WebRequest -Uri "http://localhost:8080/api/test/payment/batch?count=30").Content | ConvertFrom-Json | ForEach-Object { $_.data }

Write-Host ""
Write-Host "✅ 完成!" -ForegroundColor Green
Write-Host "查看后端Terminal窗口的JSON日志输出"
```

运行:
```powershell
.\run-batch-test.ps1
```

### 更多API选项

详见 [BATCH_TEST_API.md](BATCH_TEST_API.md)

| API | 说明 |
|-----|------|
| `GET /api/test/order` | 生成1个订单 |
| `GET /api/test/order/batch?count=N` | 生成N个订单 |
| `GET /api/test/order/scenario?count=N` | N轮业务场景测试 |
| `GET /api/test/order/stress?duration=10` | 10秒压力测试 |
| `GET /api/test/payment` | 生成1笔支付 |
| `GET /api/test/payment/batch?count=N` | 生成N笔支付 |
| `GET /api/test/payment/refund?count=N` | N轮支付+退款测试 |
| `GET /api/test/payment/stress?duration=10` | 支付压力测试 |

## �📡 测试不同的业务场景

### 场景1: 创建无效订单（价格为负数）
1. 输入负数价格: -50
2. 点击 "创建订单"
3. **预期**: 错误信息 "price must be > 0"
4. **日志**: status="client_error", error="java.lang.IllegalArgumentException"

### 场景2: 删除已支付订单（应该失败）
1. 先创建订单
2. 点击支付标记 "支付订单"
3. 点击 "删除订单"
4. **预期**: 错误信息 "Paid order cannot be deleted"
5. **日志**: 观察错误传播链路

### 场景3: 支付失败重试
1. 支付订单，如果失败（30%概率）
2. 再次点击支付按钮
3. **预期**: 最终会成功（70%成功率）
4. **日志**: 观察 duration 时间的变化

## 🔑 关键日志观察点

### 打开后端Terminal，观察JSON日志结构：

**订单创建日志:**
```
{
  "ts":"2024-02-06T10:30:45.123Z",
  "level":"INFO",
  "logger":"com.shop.recycle.order.service.OrderService",
  "msg":"订单已创建 orderId=ORD-A1B2C3D4",
  "traceId":"abc-123-def-456",
  "uri":"/api/order/create",
  "uri_group":"/order/*",
  "duration":"156",
  "userId":"user123",
  "event_class":"order",
  "error":"-",
  "status":"success",
  "thread":"http-nio-8081-exec-1",
  "app":"shop-recycle-order-service",
  "env":"local"
}
```

**日志中的关键观察:**
1. ✅ **traceId** 会在整个请求链路中保持一致
2. ✅ **uri_group** 自动规范化（/order/create → /order/*)
3. ✅ **event_class** 自动分类（order/payment/auth/api）
4. ✅ **duration** 精确到毫秒
5. ✅ **status** 自动判定（success/client_error/server_error）
6. ✅ **app** 标识发出日志的服务
7. ✅ **env** 标识环境（local/dev/prod）

## 🐛 故障排查

### 问题1: "无法连接到服务"
```
检查清单:
□ 后端服务是否全部启动 (查看Terminal有没有"Started XXXApplication")
□ 端口是否被占用: netstat -ano | findstr :8080 (Windows)
□ 防火墙是否阻止本地连接
□ 前端proxy配置是否正确 (vite.config.js)
```

### 问题2: "日志未出现"
```
检查清单:
□ logback-spring.xml是否加载成功
□ logging.level是否配置为DEBUG
□ Spring Boot是否成功启动（查看Terminal最后一行）
□ 是否有异常堆栈信息
```

### 问题3: "支付总是失败"
```
这是正常现象! Payment Service有30%的失败率用于测试。
多次点击"支付"按钮即可成功（70%成功率）。
```

### 问题4: "前端显示404错误"
```
解决方案:
1. 确认后端API Gateway启动成功 (port 8080)
2. 清除浏览器缓存 (Ctrl+Shift+Delete)
3. 检查vite.config.js中proxy配置
4. 查看浏览器开发者工具 (F12) 的Network标签
```

## 📊 进阶：接入数据采集系统

### 配置Loki（日志聚合）

在生产环境中，你可以配置Vector采集日志到Loki：

```yaml
# vector.toml配置示例
[sources.app_logs]
type = "file"
include = ["/var/log/app/*.log"]

[transforms.parse_json]
type = "remap"
inputs = ["app_logs"]
source = "parsed = parse_json!(.message)"

[sinks.loki]
type = "loki"
inputs = ["parse_json"]
endpoint = "http://loki:3100"
labels.app = "{{ app }}"
labels.event_class = "{{ event_class }}"
```

### 配置Prometheus（指标统计）

Vector会自动导出Prometheus metrics：

```promql
# QPS查询 (Prometheus)
rate(shop_recycle_requests_total[1m])

# 订单成功率
rate(shop_recycle_orders_total - shop_recycle_orders_failed_total[1m]) 
/
rate(shop_recycle_orders_total[1m])

# P95延迟
histogram_quantile(0.95, rate(shop_recycle_request_duration_ms_bucket[5m]))
```

## 📚 更多资源

- [Log.md](../Log.md) - 详细的日志架构设计文档
- [README.md](README.md) - 项目完整文档
- [Spring Cloud官方文档](https://spring.io/cloud)
- [Logstash Logback Encoder](https://github.com/logstash/logstash-logback-encoder)

## ✅ 验证清单

在开始测试前，确保你能看到以下迹象：

- [ ] 三个服务都启动成功，Terminal显示 "Started XXXApplication"
- [ ] 前端能访问 http://localhost:5173
- [ ] 能在创建订单后看到 "orderId" 返回
- [ ] 后端Terminal显示JSON格式的日志 (不是纯文本)
- [ ] 日志包含 traceId、uri_group、event_class 等字段

一旦都满足，说明你的日志系统已经准备好测试!

---

**需要帮助？** 查看 README.md 获取完整文档