# API模块更新说明

## 更新内容

根据 `fastapi_app/api.py`（最新版）更新了 `fastapi_app/app/api.py`，主要更新包括：

### 1. 添加失败重试机制

所有API函数都已添加重试机制，参考 `entry_data_list` 的实现模式：

- **默认重试次数**：20次（部分函数为10次）
- **重试逻辑**：
  - 捕获 `requests.exceptions.RequestException` 异常
  - 重试前等待时间：0.1秒（快速请求）或3-10秒（慢速请求）
  - 超过最大重试次数后记录错误日志并返回None或抛出异常

### 2. 新增功能函数

添加了以下新函数（原版本中没有的）：

- `entry_data_banch_update()` - 批量修改数据
- `entry_data_delete()` - 删除单条数据
- `entry_data_batch_delete()` - 批量删除数据
- `workflow_task_hand_over()` - 流程待办转交
- `get_upload_token()` - 获取文件上传凭证
- `upload_file()` - 上传文件

### 3. 功能增强

- **`entry_data_get()`**：
  - 添加 `replace` 参数（默认True，保持向后兼容）
  - 添加 `max_retries` 参数
  - 添加重试机制

- **`entry_data_list()`**：
  - 添加 `replace` 参数（默认True，保持向后兼容）
  - 添加 `max_retries` 参数
  - 改进重试逻辑，支持分页重试

- **`entry_widget_list()`**：
  - 添加 `max_retries` 参数
  - 添加重试机制

- **`data_batch_create()`**：
  - 添加 `max_retries` 参数
  - 添加重试机制
  - 支持 `is_start_workflow`、`is_start_trigger`、`transaction_id` 参数

- **`entry_data_batch_create()`**：
  - 添加 `max_retries` 参数
  - 添加重试机制
  - 支持 `is_start_workflow`、`is_start_trigger` 参数
  - 使用 `NpEncoder` 处理NumPy数据类型

- **`entry_data_update()`**：
  - 添加 `max_retries` 参数
  - 添加重试机制

- **`workflow_instance_get()`**：
  - 添加 `max_retries` 参数
  - 添加重试机制

- **`workflow_task_approve()`**：
  - 添加 `max_retries` 参数
  - 添加重试机制
  - `comment` 参数支持自定义（默认"自动转交"）

### 4. 工具函数

- **`NpEncoder`**：JSON编码器，处理NumPy数据类型
- **`replace_decimals()`**：递归替换Decimal类型为float

### 5. 字段替换优化

`field_replacement()` 方法使用递归实现，更优雅地处理嵌套数据结构。

## 兼容性保证

### 向后兼容

1. **默认参数**：
   - `entry_data_get()` 和 `entry_data_list()` 的 `replace` 参数默认为 `True`，保持原有行为
   - 所有新增的 `max_retries` 参数都有合理的默认值

2. **导入路径**：
   - 使用 `from app.config import Config`（而非 `from config import Config`）
   - 使用 `logging.getLogger('app')`（而非 `log_config`）

3. **函数签名**：
   - 所有原有函数的调用方式保持不变
   - 新增参数都是可选参数

### 日志系统

- 使用 `logging.getLogger('app')` 作为常规日志记录器
- 使用 `logging.getLogger('app.error')` 作为错误日志记录器
- 与 fastapi_app 项目的日志系统完全兼容

## 使用示例

### 基本使用（保持原有方式）

```python
from app.api import API

api = API()

# 获取单条数据（自动替换字段）
data = api.entry_data_get({
    'api_key': 'xxx',
    'entry_id': 'xxx',
    'data_id': 'xxx'
})

# 获取多条数据（自动替换字段）
data_list = api.entry_data_list({
    'api_key': 'xxx',
    'entry_id': 'xxx'
})
```

### 使用新功能

```python
# 不替换字段
data = api.entry_data_get({
    'api_key': 'xxx',
    'entry_id': 'xxx',
    'data_id': 'xxx'
}, replace=False)

# 自定义重试次数
data = api.entry_data_get({
    'api_key': 'xxx',
    'entry_id': 'xxx',
    'data_id': 'xxx'
}, max_retries=10)

# 批量删除
result = api.entry_data_batch_delete({
    'api_key': 'xxx',
    'entry_id': 'xxx',
    'data_ids': ['id1', 'id2', 'id3']
}, chunk_size=90, max_retries=20)
```

## 重试机制说明

### 重试策略

1. **快速请求**（0.1秒延迟）：
   - `entry_data_list()` - 分页请求
   - `entry_data_batch_create()` - 批量创建
   - `entry_data_batch_delete()` - 批量删除
   - `workflow_instance_get()` - 流程查询

2. **慢速请求**（3-10秒延迟）：
   - `data_batch_create()` - 3秒延迟
   - `entry_data_update()` - 10秒延迟
   - `entry_data_banch_update()` - 10秒延迟
   - `entry_data_delete()` - 10秒延迟
   - `workflow_task_approve()` - 3秒延迟
   - `workflow_task_hand_over()` - 3秒延迟
   - `get_upload_token()` - 3秒延迟
   - `upload_file()` - 3秒延迟

### 错误处理

- 所有重试失败的操作都会记录到错误日志
- 部分函数在重试失败后返回 `None`，部分会抛出异常
- 错误日志包含失败的任务标识信息

## 注意事项

1. **超时设置**：所有请求都设置了 `timeout=10` 秒
2. **状态码检查**：使用 `res.raise_for_status()` 检查HTTP状态码
3. **文件上传**：`upload_file()` 使用 `with` 语句确保文件正确关闭
4. **数据类型处理**：批量操作函数使用 `NpEncoder` 和 `replace_decimals()` 处理特殊数据类型

## 测试建议

1. 测试所有原有功能的兼容性
2. 测试新添加的函数
3. 测试重试机制（可以模拟网络错误）
4. 测试 `replace=False` 参数的使用