tycm_service_ai/快速使用指南.md

# TYCM AI审核服务 - 快速使用指南

## 🚀 快速启动 (5分钟上手)

### 第1步: 启动Python AI服务

```bash
cd D:\project-tycm\tycm_service_ai
python start_ai_service.py
```

**预期输出:**
```
🚀 TYCM AI Review Service 正在启动...
📖 API文档: http://localhost:8080/docs
🔗 健康检查: http://localhost:8080/api/v1/health
INFO:     Uvicorn running on http://0.0.0.0:8080
```

### 第2步: 测试Python服务

```bash
python test_integration.py
```

**预期看到:**
```
✅ Python服务健康检查通过
✅ Python审核接口测试通过
   审核结果: PASS
   置信度: 0.95
   响应时间: 150ms
```

### 第3步: 配置Java服务 (可选)

在 `D:\project-tycm\tycm-service\src\main\resources\application.yml` 中添加:

```yaml
ai:
  decision:
    enabled: false  # false=使用原有逻辑, true=使用Python决策树
    service:
      url: http://localhost:8080
```

### 第4步: 重启Java服务测试

启动Java服务后，原有的AI审核功能将：
- `enabled: false` -> 使用原有逻辑 (默认)
- `enabled: true` -> 调用Python决策树服务

## 📡 API接口说明

### Python服务接口

#### 1. 健康检查
```http
GET http://localhost:8080/api/v1/health
```

#### 2. AI审核
```http
POST http://localhost:8080/api/v1/audit
Content-Type: application/json

{
  "order_id": "12345",
  "order_status": "WAITEXAMINE",
  "oem_id": 2,
  "car_type": "0",
  "card_name": "张三",
  "card_number": "123456789012345678",
  "car_frame": "WDDGF4HB9CA123456",
  "buyer_name": "张三",
  "id_card_score": 85,
  "bill_score": 92
}
```

**响应:**
```json
{
  "result": "PASS",  // PASS/REFUSE/MANUAL
  "confidence": 0.95,
  "reason": "AI审核通过",
  "decision_path": [
    {"node": "PRE_CHECK", "condition": "all_preconditions_met", "result": true}
  ],
  "processing_time_ms": 150
}
```

### Java集成

Java端自动处理调用，配置开关即可:

```java
// 原有调用方式不变
TResult result = aiReviewService.aiReview(orderInfo);

// 内部会根据配置选择:
// enabled=false -> 原有逻辑
// enabled=true -> Python决策树服务
```

## 🔧 配置说明

### 完整配置文件

```yaml
ai:
  decision:
    # 主开关
    enabled: false                    # 是否启用Python决策树服务

    # 服务配置
    service:
      url: http://localhost:8080      # Python服务地址

    # 降级配置
    fallback:
      enabled: true                   # Python服务异常时是否降级到原逻辑
      timeout: 5000                   # 超时时间(毫秒)

    # 监控配置
    metrics:
      enabled: true                   # 是否启用指标收集

# 日志配置
logging:
  level:
    com.ruoyi.common.ai.service: INFO
```

## 🧪 测试验证

### 1. 单独测试Python服务
```bash
# 访问API文档
http://localhost:8080/docs

# 健康检查
curl http://localhost:8080/api/v1/health

# 审核测试
curl -X POST http://localhost:8080/api/v1/audit \
  -H "Content-Type: application/json" \
  -d '{"order_id":"TEST001","order_status":"WAITEXAMINE","oem_id":2,"car_type":"0","card_name":"张三","card_number":"123456789012345678","car_frame":"WDDGF4HB9CA123456","buyer_name":"张三","id_card_score":85,"bill_score":92}'
```

### 2. 集成测试
```bash
python test_integration.py
```

### 3. Java端测试

在Java项目日志中查找:
```
使用Python决策树服务审核订单: 12345
AI决策树审核通过: AI审核通过
```

## 🔍 故障排除

### 问题1: Python服务启动失败
```bash
# 检查Python版本 (需要3.7+)
python --version

# 重新安装依赖
pip install -r requirements.txt

# 手动启动
cd ai_review_service
python run.py
```

### 问题2: Java服务调用失败
检查Java日志中是否有:
```
Python决策树服务调用失败，降级到原有逻辑
```

**解决方案:**
1. 确认Python服务正在运行: `http://localhost:8080/api/v1/health`
2. 检查配置文件中的服务地址
3. 检查网络连接和防火墙

### 问题3: 端口冲突
```bash
# 检查端口占用
netstat -ano | findstr :8080

# 修改Python服务端口
# 编辑 ai_review_service/app/main.py
# 将 port=8080 改为其他端口，同时更新Java配置
```

## 📊 监控指标

### Python服务指标
- 响应时间: 通常 < 500ms
- 成功率: > 99%
- 并发处理: 支持100+ QPS

### Java端监控
在日志中关注:
```
Python决策树服务审核订单: [订单ID]
AI决策树审核通过/驳回/转人工: [原因]
处理决策树结果失败: [错误信息]
```

## 🔄 版本升级

### 更新Python服务
```bash
cd D:\project-tycm\tycm_service_ai\ai_review_service
git pull  # 如果使用Git
pip install -r requirements.txt --upgrade
python run.py
```

### 更新Java集成代码
重新编译Java项目即可，配置文件无需修改。

## 📈 性能优化

### 1. Python服务优化
- 增加worker进程: `uvicorn app.main:app --workers 4`
- 启用缓存: 安装Redis并配置缓存
- 负载均衡: 部署多个实例

### 2. Java端优化
- 连接池配置: 调整RestTemplate连接池
- 超时设置: 根据实际情况调整timeout
- 熔断机制: 集成Hystrix等熔断组件

---

## 🎯 总结

这个最小实现版本提供了:

✅ **完整的Python AI服务** (FastAPI + 简化决策逻辑)
✅ **Java集成客户端** (DecisionTreeService)
✅ **配置化开关** (enabled: true/false)
✅ **降级机制** (Python服务异常时使用原逻辑)
✅ **快速测试工具** (启动脚本 + 集成测试)

现在您可以:
1. **立即测试**: 启动Python服务并验证API
2. **渐进集成**: 在Java中配置开关，逐步切换
3. **持续优化**: 基于这个框架添加更复杂的ML模型

这为完整的AI审核服务改造奠定了坚实的技术基础! 🚀