wkc
626f7d566b
- 添加缺失的认证参数：appId, appSecretCode, role - 修复 analysisType 和 departmentCode 参数 - 将所有接口改为使用 Form 参数（form-data 格式） - 更新服务层支持字典参数 - 更新所有测试代码 - 所有测试通过（7/7）
218 lines
6.6 KiB
Markdown
218 lines
6.6 KiB
Markdown
# 接口参数修复总结
|
||
|
||
**修复日期**: 2026-03-03
|
||
**修复范围**: GetToken 接口缺少必填参数
|
||
|
||
---
|
||
|
||
## 📋 修复内容
|
||
|
||
### ✅ 1. 修复 GetTokenRequest 模型
|
||
|
||
**文件**: `models/request.py`
|
||
|
||
#### 添加的必填参数（3个）
|
||
|
||
| 参数名 | 类型 | 默认值 | 说明 |
|
||
|--------|------|--------|------|
|
||
| **appId** | `str` | `"remote_app"` | 应用ID，固定值 |
|
||
| **appSecretCode** | `str` | 必填 | 安全码，需计算 MD5 |
|
||
| **role** | `str` | `"VIEWER"` | 角色权限，固定值 |
|
||
|
||
#### 修复的类型错误（2个）
|
||
|
||
| 参数名 | 修复前 | 修复后 | 说明 |
|
||
|--------|--------|--------|------|
|
||
| **analysisType** | `Optional[int]` | `str` | 类型改为字符串 |
|
||
| **departmentCode** | `Optional[str]` | `str` | 改为必填 |
|
||
|
||
#### 修复后的完整模型
|
||
|
||
```python
|
||
class GetTokenRequest(BaseModel):
|
||
"""获取Token请求模型"""
|
||
projectNo: str = Field(..., description="项目编号，格式：902000_当前时间戳")
|
||
entityName: str = Field(..., description="项目名称")
|
||
userId: str = Field(..., description="操作人员编号，固定值")
|
||
userName: str = Field(..., description="操作人员姓名，固定值")
|
||
appId: str = Field("remote_app", description="应用ID，固定值")
|
||
appSecretCode: str = Field(..., description="安全码，md5(projectNo + '_' + entityName + '_' + dXj6eHRmPv)")
|
||
role: str = Field("VIEWER", description="角色，固定值")
|
||
orgCode: str = Field(..., description="行社机构号，固定值")
|
||
entityId: Optional[str] = Field(None, description="企业统信码或个人身份证号")
|
||
xdRelatedPersons: Optional[str] = Field(None, description="信贷关联人信息")
|
||
jzDataDateId: Optional[str] = Field("0", description="拉取指定日期推送过来的金综链流水")
|
||
innerBSStartDateId: Optional[str] = Field("0", description="拉取行内流水开始日期")
|
||
innerBSEndDateId: Optional[str] = Field("0", description="拉取行内流水结束日期")
|
||
analysisType: str = Field("-1", description="分析类型，固定值")
|
||
departmentCode: str = Field(..., description="客户经理所属营业部/分理处的机构编码")
|
||
```
|
||
|
||
---
|
||
|
||
### ✅ 2. 更新测试数据
|
||
|
||
#### 修改的文件
|
||
|
||
1. **tests/conftest.py** - 更新 `sample_token_request` fixture
|
||
2. **tests/test_api.py** - 更新测试用例
|
||
3. **tests/integration/test_full_workflow.py** - 更新集成测试
|
||
|
||
#### 更新后的测试数据示例
|
||
|
||
```python
|
||
{
|
||
"projectNo": "test_project_001",
|
||
"entityName": "测试企业",
|
||
"userId": "902001",
|
||
"userName": "902001",
|
||
"appId": "remote_app",
|
||
"appSecretCode": "test_secret_code_12345",
|
||
"role": "VIEWER",
|
||
"orgCode": "902000",
|
||
"departmentCode": "902000"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### ✅ 3. 更新文档
|
||
|
||
#### 修改的文件
|
||
|
||
**README.md** - 更新使用示例
|
||
|
||
#### 更新内容
|
||
|
||
1. 正常流程示例添加了新参数
|
||
2. 错误场景测试示例添加了新参数
|
||
|
||
---
|
||
|
||
## ✅ 测试验证
|
||
|
||
### 运行结果
|
||
|
||
```
|
||
============================= test session starts =============================
|
||
platform win32 -- Python 3.13.12, pytest-9.0.2, pluggy-1.6.0
|
||
rootdir: D:\ccdi\ccdi\.claude\worktrees\lsfx-mock-server\lsfx-mock-server
|
||
plugins: anyio-4.12.1, cov-7.0.0
|
||
collected 7 items
|
||
|
||
tests/integration/test_full_workflow.py::test_complete_workflow PASSED [ 14%]
|
||
tests/integration/test_full_workflow.py::test_all_error_codes PASSED [ 28%]
|
||
tests/integration/test_full_workflow.py::test_pagination PASSED [ 42%]
|
||
tests/test_api.py::test_root_endpoint PASSED [ 57%]
|
||
tests/test_api.py::test_health_check PASSED [ 71%]
|
||
tests/test_api.py::test_get_token_success PASSED [ 85%]
|
||
tests/test_api.py::test_get_token_error_40101 PASSED [100%]
|
||
|
||
======================== 7 passed, 1 warning in 0.08s =========================
|
||
```
|
||
|
||
**结论**: ✅ 所有 7 个测试用例通过
|
||
|
||
---
|
||
|
||
## 📊 修复前后对比
|
||
|
||
### 修复前的问题
|
||
|
||
| 问题类型 | 数量 | 严重性 |
|
||
|---------|------|--------|
|
||
| 缺少必填参数 | 3个 | 🔴 高 - 导致认证失败 |
|
||
| 类型错误 | 1个 | 🟡 中 - 可能导致数据错误 |
|
||
| 必填性错误 | 1个 | 🟡 中 - 参数校验不一致 |
|
||
|
||
### 修复后的状态
|
||
|
||
| 接口 | 参数数量 | 匹配度 | 状态 |
|
||
|------|---------|--------|------|
|
||
| 获取Token | 15个 | 100% | ✅ 完全一致 |
|
||
| 上传文件 | 2个 | 100% | ✅ 完全一致 |
|
||
| 拉取行内流水 | 7个 | 100% | ✅ 完全一致 |
|
||
| 检查解析状态 | 2个 | 100% | ✅ 完全一致 |
|
||
| 删除文件 | 3个 | 100% | ✅ 完全一致 |
|
||
| 获取银行流水 | 4个 | 100% | ✅ 完全一致 |
|
||
|
||
---
|
||
|
||
## 🎯 关键改进
|
||
|
||
### 1. 认证参数完整性
|
||
|
||
- ✅ 添加 `appId` - 应用标识
|
||
- ✅ 添加 `appSecretCode` - 安全码验证
|
||
- ✅ 添加 `role` - 角色权限控制
|
||
|
||
### 2. 数据类型准确性
|
||
|
||
- ✅ `analysisType` 从 `int` 改为 `str`，符合文档要求
|
||
- ✅ `departmentCode` 改为必填，确保数据完整性
|
||
|
||
### 3. 文档一致性
|
||
|
||
- ✅ 所有接口参数与文档完全一致
|
||
- ✅ 所有示例代码已更新
|
||
- ✅ 所有测试用例通过
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
### 1. appSecretCode 生成规则
|
||
|
||
根据文档说明，`appSecretCode` 应该按以下规则生成：
|
||
|
||
```python
|
||
import hashlib
|
||
|
||
def generate_app_secret_code(project_no: str, entity_name: str) -> str:
|
||
"""
|
||
生成安全码
|
||
格式: md5(projectNo + "_" + entityName + "_" + "dXj6eHRmPv")
|
||
"""
|
||
secret_key = "dXj6eHRmPv"
|
||
raw_string = f"{project_no}_{entity_name}_{secret_key}"
|
||
return hashlib.md5(raw_string.encode()).hexdigest()
|
||
```
|
||
|
||
### 2. 固定值参数
|
||
|
||
以下参数虽然有默认值，但仍需在请求中传递：
|
||
|
||
- `appId = "remote_app"`
|
||
- `role = "VIEWER"`
|
||
- `analysisType = "-1"`
|
||
|
||
### 3. 向后兼容性
|
||
|
||
由于新增了必填参数，此修复**不向后兼容**。所有调用 GetToken 接口的客户端需要更新请求参数。
|
||
|
||
---
|
||
|
||
## ✅ 修复验证清单
|
||
|
||
- [x] 更新 GetTokenRequest 模型（添加 3 个必填参数）
|
||
- [x] 修复 analysisType 类型（int → str）
|
||
- [x] 修复 departmentCode 必填性（可选 → 必填）
|
||
- [x] 更新测试数据（conftest.py）
|
||
- [x] 更新单元测试（test_api.py）
|
||
- [x] 更新集成测试（test_full_workflow.py）
|
||
- [x] 更新文档示例（README.md）
|
||
- [x] 运行所有测试通过（7/7 passed）
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
- [接口参数检查报告.md](./接口参数检查报告.md) - 详细的参数对比分析
|
||
- [兰溪-流水分析对接-新版.md](../../../doc/对接流水分析/兰溪-流水分析对接-新版.md) - 官方接口文档
|
||
|
||
---
|
||
|
||
**修复人员**: Claude Code
|
||
**审核状态**: ✅ 已通过测试验证
|
||
**版本**: v1.1.0
|