# 📖 接口调用示例

## 测试日期
2026-03-03

## 传输格式
**所有接口使用 Form-Data 格式** (`application/x-www-form-urlencoded`)

---

## 1️⃣ 获取 Token

### Python requests
```python
import requests

response = requests.post(
    "http://localhost:8000/account/common/getToken",
    data={  # ✅ 使用 data 参数
        "projectNo": "test_001",
        "entityName": "测试企业",
        "userId": "902001",
        "userName": "902001",
        "appId": "remote_app",
        "appSecretCode": "your_secret_code",
        "role": "VIEWER",
        "orgCode": "902000",
        "departmentCode": "902000"
    }
)

print(response.json())
```

### curl
```bash
curl -X POST http://localhost:8000/account/common/getToken \
  -d "projectNo=test_001" \
  -d "entityName=测试企业" \
  -d "userId=902001" \
  -d "userName=902001" \
  -d "appId=remote_app" \
  -d "appSecretCode=your_secret_code" \
  -d "role=VIEWER" \
  -d "orgCode=902000" \
  -d "departmentCode=902000"
```

### JavaScript fetch
```javascript
const formData = new FormData();
formData.append('projectNo', 'test_001');
formData.append('entityName', '测试企业');
formData.append('userId', '902001');
formData.append('userName', '902001');
formData.append('appId', 'remote_app');
formData.append('appSecretCode', 'your_secret_code');
formData.append('role', 'VIEWER');
formData.append('orgCode', '902000');
formData.append('departmentCode', '902000');

fetch('http://localhost:8000/account/common/getToken', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));
```

---

## 2️⃣ 上传文件

### Python requests
```python
import requests

# 获取 token 后得到 project_id
project_id = 10001

# 上传文件
files = {'file': ('statement.csv', open('statement.csv', 'rb'), 'text/csv')}
data = {'groupId': project_id}

response = requests.post(
    "http://localhost:8000/watson/api/project/remoteUploadSplitFile",
    files=files,
    data=data
)

print(response.json())
```

### curl
```bash
curl -X POST http://localhost:8000/watson/api/project/remoteUploadSplitFile \
  -F "file=@statement.csv" \
  -F "groupId=10001"
```

---

## 3️⃣ 拉取行内流水

### Python requests
```python
import requests

response = requests.post(
    "http://localhost:8000/watson/api/project/getJZFileOrZjrcuFile",
    data={
        "groupId": 10001,
        "customerNo": "330102199001011234",
        "dataChannelCode": "ZJRCU",
        "requestDateId": 20260303,
        "dataStartDateId": 20260101,
        "dataEndDateId": 20260303,
        "uploadUserId": 902001
    }
)

print(response.json())
```

### curl
```bash
curl -X POST http://localhost:8000/watson/api/project/getJZFileOrZjrcuFile \
  -d "groupId=10001" \
  -d "customerNo=330102199001011234" \
  -d "dataChannelCode=ZJRCU" \
  -d "requestDateId=20260303" \
  -d "dataStartDateId=20260101" \
  -d "dataEndDateId=20260303" \
  -d "uploadUserId=902001"
```

---

## 4️⃣ 检查文件解析状态

### Python requests
```python
import requests
import time

log_id = 10001

# 轮询检查解析状态
for i in range(10):
    response = requests.post(
        "http://localhost:8000/watson/api/project/upload/getpendings",
        data={
            "groupId": 10001,
            "inprogressList": str(log_id)
        }
    )

    result = response.json()
    print(f"第{i+1}次检查: parsing={result['data']['parsing']}")

    if not result['data']['parsing']:
        print("✅ 解析完成")
        break

    time.sleep(1)
```

### curl
```bash
curl -X POST http://localhost:8000/watson/api/project/upload/getpendings \
  -d "groupId=10001" \
  -d "inprogressList=10001"
```

---

## 5️⃣ 删除文件

### Python requests
```python
import requests

response = requests.post(
    "http://localhost:8000/watson/api/project/batchDeleteUploadFile",
    data={
        "groupId": 10001,
        "logIds": "10001,10002,10003",  # 逗号分隔的文件ID
        "userId": 902001
    }
)

print(response.json())
```

### curl
```bash
curl -X POST http://localhost:8000/watson/api/project/batchDeleteUploadFile \
  -d "groupId=10001" \
  -d "logIds=10001,10002,10003" \
  -d "userId=902001"
```

---

## 6️⃣ 获取银行流水

### Python requests
```python
import requests

response = requests.post(
    "http://localhost:8000/watson/api/project/getBSByLogId",
    data={
        "groupId": 10001,
        "logId": 10001,
        "pageNow": 1,
        "pageSize": 10
    }
)

result = response.json()
print(f"总记录数: {result['data']['totalCount']}")
print(f"当前页数据: {len(result['data']['bankStatementList'])} 条")

for statement in result['data']['bankStatementList']:
    print(f"交易日期: {statement['trxDate']}, 金额: {statement['transAmount']}")
```

### curl
```bash
curl -X POST http://localhost:8000/watson/api/project/getBSByLogId \
  -d "groupId=10001" \
  -d "logId=10001" \
  -d "pageNow=1" \
  -d "pageSize=10"
```

---

## 🔄 完整工作流程示例

### Python 完整示例
```python
import requests
import time

BASE_URL = "http://localhost:8000"

# 1. 获取 Token
print("1️⃣ 获取 Token...")
response = requests.post(
    f"{BASE_URL}/account/common/getToken",
    data={
        "projectNo": "test_001",
        "entityName": "测试企业",
        "userId": "902001",
        "userName": "902001",
        "appId": "remote_app",
        "appSecretCode": "your_code",
        "role": "VIEWER",
        "orgCode": "902000",
        "departmentCode": "902000"
    }
)

token_data = response.json()
project_id = token_data['data']['projectId']
print(f"✅ Token 获取成功，项目ID: {project_id}")

# 2. 上传文件
print("\n2️⃣ 上传文件...")
files = {'file': ('test.csv', b'test data', 'text/csv')}
data = {'groupId': project_id}
response = requests.post(
    f"{BASE_URL}/watson/api/project/remoteUploadSplitFile",
    files=files,
    data=data
)

upload_data = response.json()
log_id = upload_data['data']['uploadLogList'][0]['logId']
print(f"✅ 文件上传成功，logId: {log_id}")

# 3. 轮询检查解析状态
print("\n3️⃣ 检查解析状态...")
for i in range(10):
    response = requests.post(
        f"{BASE_URL}/watson/api/project/upload/getpendings",
        data={
            "groupId": project_id,
            "inprogressList": str(log_id)
        }
    )

    result = response.json()
    if not result['data']['parsing']:
        print(f"✅ 解析完成（第{i+1}次检查）")
        break
    print(f"⏳ 解析中...（第{i+1}次检查）")
    time.sleep(1)

# 4. 获取银行流水
print("\n4️⃣ 获取银行流水...")
response = requests.post(
    f"{BASE_URL}/watson/api/project/getBSByLogId",
    data={
        "groupId": project_id,
        "logId": log_id,
        "pageNow": 1,
        "pageSize": 5
    }
)

statements = response.json()
print(f"✅ 获取到 {statements['data']['totalCount']} 条流水记录")
print(f"   当前页显示 {len(statements['data']['bankStatementList'])} 条")

# 5. 删除文件
print("\n5️⃣ 删除文件...")
response = requests.post(
    f"{BASE_URL}/watson/api/project/batchDeleteUploadFile",
    data={
        "groupId": project_id,
        "logIds": str(log_id),
        "userId": 902001
    }
)

print(f"✅ 文件删除成功")

print("\n🎉 完整流程测试完成！")
```

---

## ⚠️ 常见错误

### ❌ 错误：使用 JSON 格式
```python
# ❌ 错误
response = requests.post(
    "http://localhost:8000/account/common/getToken",
    json={  # 错误：使用了 json 参数
        "projectNo": "test_001",
        ...
    }
)
# 返回: 422 Unprocessable Entity
```

### ✅ 正确：使用 Form-Data
```python
# ✅ 正确
response = requests.post(
    "http://localhost:8000/account/common/getToken",
    data={  # 正确：使用 data 参数
        "projectNo": "test_001",
        ...
    }
)
```

---

## 📝 Content-Type 对比

| 参数方式 | Content-Type | Swagger UI 显示 | requests 参数 |
|---------|-------------|----------------|--------------|
| JSON | `application/json` | JSON 编辑器 | `json={}` |
| Form-Data | `application/x-www-form-urlencoded` | 表单字段 | `data={}` |
| Multipart | `multipart/form-data` | 文件上传 | `files={}, data={}` |

---

## 🎯 快速测试脚本

保存为 `test_api.py`:
```python
import requests

BASE_URL = "http://localhost:8000"

# 测试获取 Token
response = requests.post(
    f"{BASE_URL}/account/common/getToken",
    data={
        "projectNo": "test_001",
        "entityName": "测试企业",
        "userId": "902001",
        "userName": "902001",
        "appId": "remote_app",
        "appSecretCode": "test_code",
        "role": "VIEWER",
        "orgCode": "902000",
        "departmentCode": "902000"
    }
)

if response.status_code == 200:
    print("✅ 接口测试成功")
    print(response.json())
else:
    print(f"❌ 接口测试失败: {response.status_code}")
    print(response.text)
```

运行测试：
```bash
python test_api.py
```

---

**文档创建日期**: 2026-03-03
**适用版本**: v1.4.0