QAUP_Management/adxp-adapter/QUICKSTART.md

# ADXP SDK Adapter 快速开始

## 方案概述

ADXP SDK (adxp-client-2.6.9.jar) 基于 JDK 8 开发，无法在 Java 11+ 环境运行。本方案通过独立的适配器服务解决兼容性问题。

### 架构

```
主应用 (Java 17) → HTTP → ADXP Adapter (Java 8, Docker) → SOAP → 数据中台
     └─ port 8080          └─ port 8086                      └─ port 7001
```

### Apple Silicon (M1/M2/M3) 用户

✅ **推荐使用 Docker**，无需安装 Java 8（Homebrew 的 openjdk@8 只有 x86_64 版本）

---

## 🚀 快速开始（Docker 方式，推荐）

### 步骤 1: 启动 Mock 服务器（模拟数据中台）

```bash
# 在项目根目录
cd tools
python3 mock_adxp.py --host 0.0.0.0 --port 7001 --auto --interval 10
```

**说明**: Mock 服务器监听 `0.0.0.0:7001`，每 10 秒自动生成航班消息

### 步骤 2: 编译适配器服务

```bash
cd ../adxp-adapter
mvn clean package -DskipTests
```

**预期输出**: `BUILD SUCCESS`，生成 `target/adxp-adapter.jar`

### 步骤 3: 构建 Docker 镜像

```bash
docker build -t adxp-adapter:1.0.0 .
```

**说明**: 使用 OpenJDK 8（非 Alpine），包含 `net-tools`（SDK 需要 `ifconfig` 命令）

### 步骤 4: 启动 Docker 容器

```bash
docker run -d \
  -p 8086:8086 \
  -e ADXP_HOST=host.docker.internal \
  -e ADXP_PORT=7001 \
  --name adxp-adapter \
  adxp-adapter:1.0.0
```

**说明**: 
- `host.docker.internal` 指向宿主机（访问本地 mock 服务器）
- 环境变量可覆盖配置文件

### 步骤 5: 验证适配器服务

```bash
# 健康检查
curl http://localhost:8086/api/adxp/health

# 预期输出: {"activeSessions":0,"status":"UP"}
```

### 步骤 6: 测试完整流程

```bash
# 1. 登录
LOGIN_RESPONSE=$(curl -s -X POST http://localhost:8086/api/adxp/login \
  -H "Content-Type: application/json" \
  -d '{"username":"dianxin","password":"dianxin@123"}')

echo "登录响应: $LOGIN_RESPONSE"
# 预期: {"success":true,"sessionId":"xxx-xxx-xxx","message":"登录成功"}

# 2. 提取 SessionId
SESSION_ID=$(echo "$LOGIN_RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['sessionId'])")
echo "SessionId: $SESSION_ID"

# 3. 接收消息
curl -s "http://localhost:8086/api/adxp/messages?sessionId=$SESSION_ID" | python3 -m json.tool

# 4. 退出登录
curl -s -X POST http://localhost:8086/api/adxp/logout \
  -H "Content-Type: application/json" \
  -d "{\"sessionId\":\"$SESSION_ID\"}" | python3 -m json.tool

# 预期: {"success":true,"message":"登出成功"}
```

### 步骤 7: 启动主应用

```bash
cd ../qaup-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev,druid
```

**主应用会自动通过 HTTP 调用适配器服务！**

---

## 📋 Docker 常用命令

```bash
# 查看日志
docker logs -f adxp-adapter

# 重启容器
docker restart adxp-adapter

# 停止并删除容器
docker stop adxp-adapter && docker rm adxp-adapter

# 重新构建镜像（代码修改后）
cd adxp-adapter
mvn clean package -DskipTests
docker stop adxp-adapter && docker rm adxp-adapter
docker build -t adxp-adapter:1.0.0 .
docker run -d -p 8086:8086 -e ADXP_HOST=host.docker.internal -e ADXP_PORT=7001 --name adxp-adapter adxp-adapter:1.0.0
```

---

## 🛠️ 本地运行（需要 Java 8）

**仅适用于 x86_64 机器或已安装 Java 8 的环境**

### 步骤 1: 启动 Mock 服务器

```bash
cd tools
python3 mock_adxp.py --host 0.0.0.0 --port 7001 --auto --interval 10
```

### 步骤 2: 编译

```bash
cd ../adxp-adapter
mvn clean package -DskipTests
```

### 步骤 3: 启动适配器

```bash
# 如果系统默认是 Java 8
java -jar target/adxp-adapter.jar

# 或指定 Java 8 路径
/path/to/jdk8/bin/java -jar target/adxp-adapter.jar

# 或使用启动脚本（自动查找 Java 8）
./start.sh
```

### 步骤 4: 测试

同 Docker 方式的步骤 6

## 配置说明

### 主应用配置 (application-dev.yml)

```yaml
data:
  collector:
    adxp-adapter:
      host: localhost        # 适配器服务地址
      port: 8086             # 适配器服务端口
      username: dianxin
      password: dianxin@123
      reconnect-delay-millis: 3000
```

### 适配器服务配置 (application.yml)

```yaml
adxp:
  host: localhost  # 真实数据中台地址（或 mock 服务器）
  port: 7001       # 数据中台端口
```

---

## 🐳 Docker Compose 部署（生产环境）

### 1. 准备环境变量

```bash
# 创建 .env 文件
cat > .env << EOF
ADXP_HOST=10.10.10.100  # 真实数据中台 IP
ADXP_PORT=7001          # 真实数据中台端口
EOF
```

### 2. 编译和构建

```bash
cd adxp-adapter
mvn clean package -DskipTests
docker build -t adxp-adapter:1.0.0 .
```

### 3. 启动服务

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

# 查看日志
docker-compose logs -f adxp-adapter

# 查看状态
docker-compose ps
```

### 4. 验证部署

```bash
# 健康检查
curl http://localhost:8086/api/adxp/health

# 测试登录
curl -X POST http://localhost:8086/api/adxp/login \
  -H "Content-Type: application/json" \
  -d '{"username":"dianxin","password":"dianxin@123"}'
```

### 5. 停止服务

```bash
docker-compose down
```

---

## 🔧 环境切换

### 开发环境（使用 Mock）

**主应用配置** (`qaup-admin/src/main/resources/application-dev.yml`):
```yaml
data:
  collector:
    adxp-adapter:
      host: localhost
      port: 8086
      username: dianxin
      password: dianxin@123
      reconnect-delay-millis: 3000
```

**适配器配置** (`.env` 或环境变量):
```bash
ADXP_HOST=host.docker.internal  # 指向宿主机 mock 服务器
ADXP_PORT=7001
```

**Mock 服务器**:
```bash
python3 tools/mock_adxp.py --host 0.0.0.0 --port 7001 --auto --interval 10
```

### 生产环境（连接真实数据中台）

**主应用配置** (`qaup-admin/src/main/resources/application-prod.yml`):
```yaml
data:
  collector:
    adxp-adapter:
      host: 192.168.1.100  # 适配器服务的真实 IP
      port: 8086
      username: ${ADXP_USERNAME}  # 从环境变量读取
      password: ${ADXP_PASSWORD}
      reconnect-delay-millis: 3000
```

**适配器配置** (`.env` 文件):
```bash
ADXP_HOST=10.10.10.100  # 真实数据中台 IP
ADXP_PORT=7001
```

---

## 🐛 故障排查

### 问题 1: Docker 容器启动失败

**检查日志**:
```bash
docker logs adxp-adapter
```

**常见错误**:
- `Cannot find ifconfig` → Dockerfile 使用了 Alpine 镜像，应使用 `openjdk:8-jdk`
- `Connection refused` → Mock 服务器未启动或端口错误

### 问题 2: 登录失败 (code=802/803)

**原因**: SDK 无法连接到数据中台

**排查步骤**:
```bash
# 1. 检查 mock 服务器是否运行
lsof -ti:7001

# 2. 测试网络连接
curl http://localhost:7001/LoginService?wsdl

# 3. 检查适配器环境变量
docker exec adxp-adapter env | grep ADXP

# 4. 查看适配器日志
docker logs adxp-adapter 2>&1 | grep -E "ERROR|Exception"
```

### 问题 3: HTTP 406 Not Acceptable

**原因**: DTO 类缺少 getter/setter 方法

**解决方案**: 
- 确保 `LoginResponse`、`MessageResponse` 有显式的 getter/setter（不要只依赖 Lombok）
- 确保 `jackson-databind` 依赖存在

**验证**:
```bash
# 查看 pom.xml 中的 Jackson 依赖
grep -A 5 "jackson-databind" adxp-adapter/pom.xml
```

### 问题 4: Apple Silicon 兼容性

**错误**: `openjdk@8: The x86_64 architecture is required`

**解决方案**: 使用 Docker（推荐），或使用 Rosetta 2 运行 x86_64 版本

### 问题 5: Mock 响应格式错误

**症状**: SDK 返回 code=803 "发送请求错误"

**排查**:
```bash
# 查看 mock 服务器日志
tail -f /tmp/mock_adxp.log

# 检查 SOAP 响应格式
curl -X POST http://localhost:7001/LoginService \
  -H "Content-Type: text/xml" \
  -d '<?xml version="1.0"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body><log:login xmlns:log="http://LoginService">
    <username>dianxin</username><password>dianxin@123</password>
  </log:login></soapenv:Body>
</soapenv:Envelope>'
```

---

## 📊 监控和日志

### 健康检查端点

```bash
# 适配器健康状态
curl http://localhost:8086/api/adxp/health
# 返回: {"activeSessions":0,"status":"UP"}

# Spring Boot Actuator
curl http://localhost:8086/actuator/health
```

### 日志查看

```bash
# Docker 容器日志
docker logs -f adxp-adapter

# 实时过滤错误
docker logs -f adxp-adapter 2>&1 | grep -E "ERROR|WARN"

# Mock 服务器日志
tail -f /tmp/mock_adxp.log

# 主应用日志
tail -f qaup-admin/app.log | grep -E "adxp|flight"
```

### 性能监控

```bash
# 容器资源使用
docker stats adxp-adapter

# 网络延迟测试
time curl -s http://localhost:8086/api/adxp/health
```

---

## 📈 性能指标

- **HTTP 延迟**: < 5ms（局域网）
- **适配器内存**: ~256MB（基础）+ SDK 使用
- **并发支持**: 多个主应用实例可共享一个适配器
- **会话管理**: 自动重连，无需手动维护

---

## ✅ 验收检查清单

部署前请确认：

- [ ] Mock 服务器正常运行（开发环境）
- [ ] 适配器 Docker 镜像构建成功
- [ ] 适配器容器启动成功
- [ ] 健康检查返回 `{"status":"UP"}`
- [ ] 登录测试成功，返回 sessionId
- [ ] 主应用能通过 HTTP 调用适配器
- [ ] 日志中无 ERROR 级别错误

---

## 🚀 下一步

1. ✅ **开发环境测试完成** - Mock 服务器 + 适配器正常工作
2. 🔧 **生产部署** - 修改 ADXP_HOST 连接真实数据中台
3. 📊 **监控集成** - 添加 Prometheus metrics（可选）
4. 🔒 **安全加固** - 添加 API 认证/授权（可选）
5. 📦 **K8s 部署** - 创建 Deployment 和 Service 配置（可选）