# 📋 Form-Data 修复说明

## 修复日期
2026-03-03

## 问题描述
原代码中使用 JSON body 方式传输参数，但接口文档要求使用 form-data (application/x-www-form-urlencoded) 方式传输。

## 修复内容

### 1. 修改接口参数接收方式
将所有接口从 `json=` 改为 `data=` 或 `Form=`

**修改的文件：**
- `routers/api.py` - 所有接口改为使用 Form 参数

- `models/request.py` - 更新请求模型
- `tests/` - 所有测试代码更新为使用 data 参数
- `README.md` - 更新示例代码

### 2. 修改的接口

#### 接口1: 获取Token
- **修改前**: 使用 `json=GetTokenRequest` 接收 JSON body
- **修改后**: 使用 Form 参数分别接收每个字段

```python
# 修改前
async def get_token(request: GetTokenRequest):
    ...

# 修改后
async def get_token(
    projectNo: str = Form(...),
    entityName: str = Form(...),
    userId: str = Form(...),
    # ... 其他参数
):
    # 构建请求对象
    request = GetTokenRequest(...)
    ...
```

#### 接口3: 拉取行内流水
- **修改前**: 使用 `json=FetchInnerFlowRequest`
- **修改后**: 使用 Form 参数

#### 接口4: 检查解析状态
- **修改前**: 使用 `json=CheckParseStatusRequest`
- **修改后**: 使用 Form 参数

#### 接口5: 删除文件
- **修改前**: 使用 `json=DeleteFilesRequest`
- **修改后**: 使用 Form 参数
- **特殊处理**: `logIds` 从数组改为逗号分隔的字符串

```python
# 前端传递: logIds=10001,10002,10003
# 后端处理:
log_id_list = [int(id.strip()) for id in logIds.split(",")]
```

#### 接口6: 获取银行流水
- **修改前**: 使用 `json=GetBankStatementRequest`
- **修改后**: 使用 Form 参数

### 3. 测试代码更新
所有测试从 `json=` 改为 `data=`
```python
# 修改前
response = client.post("/account/common/getToken", json=request_data)

# 修改后
response = client.post("/account/common/getToken", data=request_data)
```
### 4. 文档更新
README.md 中的示例代码更新为使用 `data=` 参数:
```python
# 修改前
json={
    "projectNo": "test_project_001",
    ...
}

# 修改后
data={
    "projectNo": "test_project_001",
    ...
}
```
## 测试结果
✅ **所有测试通过 (7/7)**
```bash
======================== 7 passed, 1 warning in 0.08s =========================
```
## 使用示例
### curl 请求
```bash
# 使用 form-data 方式
curl -X POST http://localhost:8000/account/common/getToken \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "projectNo=test_project_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"
```
### Python requests 请求
```python
# 使用 form-data 方式
response = requests.post(
    "http://localhost:8000/account/common/getToken",
    data={
        "projectNo": "test_project_001",
        "entityName": "测试企业",
        "userId": "902001",
        "userName": "902001",
        "appId": "remote_app",
        "appSecretCode": "your_secret_code",
        "role": "VIEWER",
        "orgCode": "902000",
        "departmentCode": "902000"
    }
)
```
## 注意事项
1. **Content-Type**: 所有接口现在使用 `application/x-www-form-urlencoded`
2. **数组参数**: 如 `logIds` 需要传递逗号分隔的字符串，如: `"10001,10002,10003"`
3. **可选参数**: 可选参数可以不传或传空值
4. **测试验证**: 所有 7 个测试用例全部通过
## 影响范围
- ✅ 不向后兼容
- ⚠️ 所有调用这些接口的客户端需要更新为使用 form-data 方式
- ⚠️ Swagger UI 会自动显示正确的参数格式
## 修复验证
- [x] 修改所有接口使用 Form 参数
- [x] 更新所有测试代码
- [x] 运行测试通过 (7/7)
- [x] 创建修复文档
## 修复状态
✅ **已完成** - 所有接口已改为 form-data 方式，测试全部通过