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 模型

当前代码：

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

应修改为：

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