ccdi/接口参数检查报告.md

# 接口参数对比检查报告

**检查时间**: 2026-03-03
**检查范围**: lsfx-mock-server 所有接口参数与文档对比

---

## 📋 总览

| 接口序号 | 接口名称 | 状态 | 问题数量 |
|---------|---------|------|---------|
| 1 | 新建项目并获取token | ❌ **严重** | 5个问题 |
| 2 | 上传文件接口 | ✅ 一致 | 0个问题 |
| 3 | 拉取行内流水接口 | ✅ 一致 | 0个问题 |
| 4 | 判断文件是否解析结束 | ✅ 一致 | 0个问题 |
| 5 | 删除文件接口 | ⚠️ 额外实现 | 文档中未提及 |
| 6 | 获取流水列表 | ✅ 一致 | 0个问题 |

---

## 1️⃣ 新建项目并获取token - ❌ **严重问题**

### 缺少的必填参数（3个）

| 参数名 | 文档要求 | 代码实现 | 严重性 |
|--------|---------|---------|--------|
| **appId** | `String` 必填，固定值 `"remote_app"` | ❌ **缺失** | 🔴 高 - 认证参数 |
| **appSecretCode** | `String` 必填，安全码 | ❌ **缺失** | 🔴 高 - 认证参数 |
| **role** | `String` 必填，固定值 `"VIEWER"` | ❌ **缺失** | 🟡 中 - 权限参数 |

### 类型错误（1个）

| 参数名 | 文档要求 | 代码实现 | 说明 |
|--------|---------|---------|------|
| **analysisType** | `String` 必填 | `Optional[int]` 可选 | 应改为 `str` 类型 |

### 必填性错误（1个）

| 参数名 | 文档要求 | 代码实现 | 说明 |
|--------|---------|---------|------|
| **departmentCode** | 必填 | `Optional[str]` 可选 | 应改为必填 |

### 完整参数对比表（15个参数）

| 序号 | 参数名 | 文档类型 | 文档必填 | 代码类型 | 代码必填 | 状态 |
|-----|--------|---------|---------|---------|---------|------|
| 1 | projectNo | String | ✅ 是 | str | ✅ 是 | ✅ |
| 2 | entityName | String | ✅ 是 | str | ✅ 是 | ✅ |
| 3 | userId | String | ✅ 是 | str | ✅ 是 | ✅ |
| 4 | userName | String | ✅ 是 | str | ✅ 是 | ✅ |
| 5 | **appId** | String | ✅ 是 | - | - | ❌ **缺失** |
| 6 | **appSecretCode** | String | ✅ 是 | - | - | ❌ **缺失** |
| 7 | **role** | String | ✅ 是 | - | - | ❌ **缺失** |
| 8 | orgCode | String | ✅ 是 | str | ✅ 是 | ✅ |
| 9 | entityId | String | 否 | Optional[str] | 否 | ✅ |
| 10 | xdRelatedPersons | String | 否 | Optional[str] | 否 | ✅ |
| 11 | jzDataDateId | String | 否 | Optional[str] | 否 | ✅ |
| 12 | innerBSStartDateId | String | 否 | Optional[str] | 否 | ✅ |
| 13 | innerBSEndDateId | String | 否 | Optional[str] | 否 | ✅ |
| 14 | **analysisType** | String | ✅ 是 | Optional[int] | 否 | ⚠️ **类型错误** |
| 15 | **departmentCode** | String | ✅ 是 | Optional[str] | 否 | ⚠️ **必填性错误** |

---

## 2️⃣ 上传文件接口 - ✅ **完全一致**

### 请求参数对比

| 参数名 | 文档类型 | 文档必填 | 代码类型 | 代码必填 | 状态 |
|--------|---------|---------|---------|---------|------|
| groupId | Int | ✅ 是 | int (Form) | ✅ 是 | ✅ |
| file | File | ✅ 是 | UploadFile | ✅ 是 | ✅ |

**结论**: 参数完全一致，无缺失。

---

## 3️⃣ 拉取行内流水接口 - ✅ **完全一致**

### 请求参数对比

| 参数名 | 文档类型 | 文档必填 | 代码类型 | 代码必填 | 状态 |
|--------|---------|---------|---------|---------|------|
| groupId | Int | ✅ 是 | int | ✅ 是 | ✅ |
| customerNo | String | ✅ 是 | str | ✅ 是 | ✅ |
| dataChannelCode | String | ✅ 是 | str | ✅ 是 | ✅ |
| requestDateId | Int | ✅ 是 | int | ✅ 是 | ✅ |
| dataStartDateId | Int | ✅ 是 | int | ✅ 是 | ✅ |
| dataEndDateId | Int | ✅ 是 | int | ✅ 是 | ✅ |
| uploadUserId | int | ✅ 是 | int | ✅ 是 | ✅ |

**结论**: 参数完全一致，无缺失。

---

## 4️⃣ 判断文件是否解析结束 - ✅ **完全一致**

### 请求参数对比

| 参数名 | 文档类型 | 文档必填 | 代码类型 | 代码必填 | 状态 |
|--------|---------|---------|---------|---------|------|
| groupId | Int | ✅ 是 | int | ✅ 是 | ✅ |
| inprogressList | String | ✅ 是 | str | ✅ 是 | ✅ |

**结论**: 参数完全一致，无缺失。

---

## 5️⃣ 删除文件接口 - ⚠️ **文档中未提及**

### 代码实现的参数

| 参数名 | 代码类型 | 代码必填 |
|--------|---------|---------|
| groupId | int | ✅ 是 |
| logIds | List[int] | ✅ 是 |
| userId | int | ✅ 是 |

**结论**: 接口路径 `/watson/api/project/batchDeleteUploadFile` 在文档的调用流程中提到，但没有详细的参数说明文档。

---

## 6️⃣ 获取流水列表 - ✅ **完全一致**

### 请求参数对比

| 参数名 | 文档类型 | 文档必填 | 代码类型 | 代码必填 | 状态 |
|--------|---------|---------|---------|---------|------|
| groupId | Int | ✅ 是 | int | ✅ 是 | ✅ |
| logId | Int | ✅ 是 | int | ✅ 是 | ✅ |
| pageNow | Int | ✅ 是 | int | ✅ 是 | ✅ |
| pageSize | Int | ✅ 是 | int | ✅ 是 | ✅ |

**结论**: 参数完全一致，无缺失。

---

## 🎯 总结

### ❌ **严重问题**

**接口1 - 获取Token接口缺少3个关键认证参数：**
- `appId` - 固定值 `"remote_app"`
- `appSecretCode` - 安全码，格式为 `md5(projectNo + "_" + entityName + "_" + dXj6eHRmPv)`
- `role` - 固定值 `"VIEWER"`

这3个参数缺失会导致接口调用失败（错误码 40101, 40102）。

### ⚠️ **次要问题**

1. `analysisType` 类型应为 `str` 而非 `int`
2. `departmentCode` 应为必填而非可选

### ✅ **正常接口**

其他5个接口参数完全一致，无缺失问题。

---

## 📝 修复建议

### 1. 修复 GetTokenRequest 模型

**当前代码：**
```python
class GetTokenRequest(BaseModel):
    projectNo: str
    entityName: str
    userId: str
    userName: str
    orgCode: str
    entityId: Optional[str] = None
    xdRelatedPersons: Optional[str] = None
    jzDataDateId: Optional[str] = "0"
    innerBSStartDateId: Optional[str] = "0"
    innerBSEndDateId: Optional[str] = "0"
    analysisType: Optional[int] = -1
    departmentCode: Optional[str] = None
```

**应修改为：**
```python
class GetTokenRequest(BaseModel):
    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. 注意事项

- `appSecretCode` 需要在服务端计算 MD5 值
- `appId` 和 `role` 虽然是固定值，但仍需在请求体中传递
- `analysisType` 应为字符串类型 `"-1"`，而不是整数 `-1`

---

**检查完成时间**: 2026-03-03
**检查人员**: Claude Code