374 lines
12 KiB
Markdown
374 lines
12 KiB
Markdown
# 获取单个文件上传状态接口优化设计
|
||
|
||
## 文档信息
|
||
|
||
- **创建日期**: 2026-03-12
|
||
- **设计者**: Claude Code
|
||
- **状态**: 待实施
|
||
|
||
## 1. 需求背景
|
||
|
||
### 1.1 接口信息
|
||
|
||
- **接口路径**: `/watson/api/project/bs/upload` (GET)
|
||
- **接口名称**: 获取单个文件上传后的状态
|
||
- **项目背景**: 流水分析 Mock 服务器
|
||
|
||
### 1.2 当前问题
|
||
|
||
当前实现存在以下问题：
|
||
|
||
1. **依赖实际上传记录**: 接口依赖 `self.file_records`（上传时存储的记录），如果没有上传过文件，logs 返回空数组
|
||
2. **不符合 Mock 服务器定位**: Mock 服务器应该独立工作，前端测试时不应依赖其他接口
|
||
3. **字段值不正确**: `logMeta` 字段中的 `balanceAmount` 值为布尔值 `true`，应该为字符串 `"-1"`
|
||
|
||
### 1.3 期望行为
|
||
|
||
根据接口文档（`assets/兰溪-流水分析对接3.md` 第374-516行）：
|
||
|
||
1. **带 logId 参数**: 根据 logId 生成固定的文件记录数据（相同 logId 返回相同数据）
|
||
2. **不带 logId 参数**: 返回空的 logs 数组
|
||
3. **固定成功状态**: status=-5, uploadStatusDesc="data.wait.confirm.newaccount"
|
||
4. **独立性**: 不依赖实际上传的文件记录，接口独立工作
|
||
|
||
## 2. 解决方案
|
||
|
||
### 2.1 设计原则
|
||
|
||
1. **确定性随机**: 使用 `random.seed(log_id)` 确保相同 logId 生成相同数据
|
||
2. **完全独立**: 不依赖 `self.file_records`，在 `get_upload_status()` 中直接生成数据
|
||
3. **文档对齐**: 严格遵循接口文档示例的字段和格式
|
||
4. **简单高效**: 代码简洁，易于维护和测试
|
||
|
||
### 2.2 核心设计
|
||
|
||
#### 2.2.1 数据生成策略
|
||
|
||
**基于 logId 的确定性随机生成**
|
||
|
||
```python
|
||
def get_upload_status(self, group_id: int, log_id: int = None) -> dict:
|
||
"""
|
||
获取文件上传状态
|
||
|
||
Args:
|
||
group_id: 项目ID
|
||
log_id: 文件ID（可选）
|
||
|
||
Returns:
|
||
上传状态响应字典
|
||
"""
|
||
logs = []
|
||
|
||
if log_id:
|
||
# 使用 logId 作为随机种子，确保相同 logId 返回相同数据
|
||
random.seed(log_id)
|
||
|
||
# 生成确定性的文件记录
|
||
record = self._generate_deterministic_record(log_id, group_id)
|
||
logs.append(record)
|
||
|
||
# 返回响应
|
||
return {
|
||
"code": "200",
|
||
"data": {
|
||
"logs": logs,
|
||
"status": "",
|
||
"accountId": 8954,
|
||
"currency": "CNY"
|
||
},
|
||
"status": "200",
|
||
"successResponse": True
|
||
}
|
||
```
|
||
|
||
#### 2.2.2 字段生成规则
|
||
|
||
根据文档示例（`assets/兰溪-流水分析对接3.md` 第431-499行），logs 数组中的每个对象包含 26 个字段：
|
||
|
||
| 字段名 | 生成规则 | 示例值 |
|
||
|--------|----------|--------|
|
||
| accountNoList | 11位随机数字 | ["18785967364"] |
|
||
| bankName | 从3种银行中随机选择 | "ALIPAY" |
|
||
| dataTypeInfo | 固定值 | ["CSV", ","] |
|
||
| downloadFileName | 基于 logId 生成 | "测试文件_13994.csv" |
|
||
| enterpriseNameList | 70%概率有主体，30%为空 | ["测试主体"] 或 [""] |
|
||
| fileSize | 随机范围 10000-100000 | 16322 |
|
||
| fileUploadBy | 固定值 | 448 |
|
||
| fileUploadByUserName | 固定值 | "admin@support.com" |
|
||
| fileUploadTime | 当前时间 | "2025-03-13 08:45:32" |
|
||
| isSplit | 固定值 | 0 |
|
||
| leId | 10000 + 随机数 | 10741 |
|
||
| logId | 参数传入 | 13994 |
|
||
| logMeta | **修复为字符串 "-1"** | "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}" |
|
||
| logType | 固定值 | "bankstatement" |
|
||
| loginLeId | 10000 + 随机数 | 10741 |
|
||
| lostHeader | 固定空数组 | [] |
|
||
| realBankName | 与 bankName 一致 | "ALIPAY" |
|
||
| rows | 固定值 | 0 |
|
||
| source | 固定值 | "http" |
|
||
| status | 固定成功值 | -5 |
|
||
| templateName | 根据银行选择对应模板 | "ALIPAY_T220708" |
|
||
| totalRecords | 随机范围 100-300 | 127 |
|
||
| trxDateEndId | 当前日期 | 20231231 |
|
||
| trxDateStartId | 当前日期 - 随机90-365天 | 20230102 |
|
||
| uploadFileName | 基于 logId 生成 | "测试文件_13994.pdf" |
|
||
| uploadStatusDesc | 固定成功描述 | "data.wait.confirm.newaccount" |
|
||
|
||
#### 2.2.3 银行类型映射
|
||
|
||
| bankName | templateName | realBankName |
|
||
|----------|--------------|--------------|
|
||
| "ALIPAY" | "ALIPAY_T220708" | "ALIPAY" |
|
||
| "BSX" | "BSX_T240925" | "BSX" |
|
||
| "ZJRCU" | "ZJRCU_T251114" | "ZJRCU" |
|
||
|
||
### 2.3 关键修复点
|
||
|
||
#### 修复1: logMeta 字段
|
||
|
||
**当前实现**（`services/file_service.py:47`）:
|
||
```python
|
||
log_meta: str = "{\"lostHeader\":[],\"balanceAmount\":true}" # ❌ 错误
|
||
```
|
||
|
||
**修复后**:
|
||
```python
|
||
log_meta: str = "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}" # ✅ 正确
|
||
```
|
||
|
||
#### 修复2: 独立数据生成
|
||
|
||
**当前实现**: 依赖 `self.file_records`
|
||
|
||
**修复后**: 在 `get_upload_status()` 中独立生成数据，不依赖上传记录
|
||
|
||
## 3. 技术设计
|
||
|
||
### 3.1 修改文件清单
|
||
|
||
| 文件 | 修改内容 |
|
||
|------|----------|
|
||
| `services/file_service.py` | 1. 修复 FileRecord.log_meta 默认值<br>2. 重构 get_upload_status() 方法<br>3. 新增 _generate_deterministic_record() 方法 |
|
||
|
||
### 3.2 核心代码实现
|
||
|
||
#### 3.2.1 新增方法: _generate_deterministic_record()
|
||
|
||
```python
|
||
def _generate_deterministic_record(self, log_id: int, group_id: int) -> dict:
|
||
"""
|
||
基于 logId 生成确定性的文件记录
|
||
|
||
Args:
|
||
log_id: 文件ID（用作随机种子）
|
||
group_id: 项目ID
|
||
|
||
Returns:
|
||
文件记录字典（26个字段）
|
||
"""
|
||
# 银行类型选项
|
||
bank_options = [
|
||
("ALIPAY", "ALIPAY_T220708"),
|
||
("BSX", "BSX_T240925"),
|
||
("ZJRCU", "ZJRCU_T251114")
|
||
]
|
||
|
||
bank_name, template_name = random.choice(bank_options)
|
||
|
||
# 生成交易日期范围
|
||
end_date = datetime.now()
|
||
start_date = end_date - timedelta(days=random.randint(90, 365))
|
||
|
||
# 生成账号和主体
|
||
account_no = f"{random.randint(10000000000, 99999999999)}"
|
||
enterprise_names = ["测试主体"] if random.random() > 0.3 else [""]
|
||
|
||
return {
|
||
"accountNoList": [account_no],
|
||
"bankName": bank_name,
|
||
"dataTypeInfo": ["CSV", ","],
|
||
"downloadFileName": f"测试文件_{log_id}.csv",
|
||
"enterpriseNameList": enterprise_names,
|
||
"fileSize": random.randint(10000, 100000),
|
||
"fileUploadBy": 448,
|
||
"fileUploadByUserName": "admin@support.com",
|
||
"fileUploadTime": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
|
||
"isSplit": 0,
|
||
"leId": 10000 + random.randint(0, 9999),
|
||
"logId": log_id,
|
||
"logMeta": "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}",
|
||
"logType": "bankstatement",
|
||
"loginLeId": 10000 + random.randint(0, 9999),
|
||
"lostHeader": [],
|
||
"realBankName": bank_name,
|
||
"rows": 0,
|
||
"source": "http",
|
||
"status": -5,
|
||
"templateName": template_name,
|
||
"totalRecords": random.randint(100, 300),
|
||
"trxDateEndId": int(end_date.strftime("%Y%m%d")),
|
||
"trxDateStartId": int(start_date.strftime("%Y%m%d")),
|
||
"uploadFileName": f"测试文件_{log_id}.pdf",
|
||
"uploadStatusDesc": "data.wait.confirm.newaccount"
|
||
}
|
||
```
|
||
|
||
#### 3.2.2 重构方法: get_upload_status()
|
||
|
||
```python
|
||
def get_upload_status(self, group_id: int, log_id: int = None) -> dict:
|
||
"""
|
||
获取文件上传状态（基于 logId 生成确定性数据）
|
||
|
||
Args:
|
||
group_id: 项目ID
|
||
log_id: 文件ID（可选）
|
||
|
||
Returns:
|
||
上传状态响应字典
|
||
"""
|
||
logs = []
|
||
|
||
if log_id:
|
||
# 使用 logId 作为随机种子，确保相同 logId 返回相同数据
|
||
random.seed(log_id)
|
||
|
||
# 生成确定性的文件记录
|
||
record = self._generate_deterministic_record(log_id, group_id)
|
||
logs.append(record)
|
||
|
||
# 返回响应
|
||
return {
|
||
"code": "200",
|
||
"data": {
|
||
"logs": logs,
|
||
"status": "",
|
||
"accountId": 8954,
|
||
"currency": "CNY"
|
||
},
|
||
"status": "200",
|
||
"successResponse": True
|
||
}
|
||
```
|
||
|
||
### 3.3 测试设计
|
||
|
||
#### 3.3.1 测试场景
|
||
|
||
1. **带 logId 查询**: 验证返回非空 logs 数组
|
||
2. **不带 logId 查询**: 验证返回空 logs 数组
|
||
3. **确定性测试**: 相同 logId 多次调用返回相同数据
|
||
4. **字段完整性**: 验证返回的 26 个字段都存在
|
||
5. **字段值正确性**: 验证 status=-5, logMeta 格式正确
|
||
6. **银行类型随机性**: 验证不同 logId 生成不同银行类型
|
||
|
||
#### 3.3.2 测试用例示例
|
||
|
||
```python
|
||
def test_get_upload_status_with_log_id():
|
||
"""测试带 logId 参数查询"""
|
||
response = client.get("/watson/api/project/bs/upload?groupId=1000&logId=13994")
|
||
|
||
assert response.status_code == 200
|
||
data = response.json()
|
||
|
||
assert data["code"] == "200"
|
||
assert len(data["data"]["logs"]) == 1
|
||
assert data["data"]["logs"][0]["logId"] == 13994
|
||
assert data["data"]["logs"][0]["status"] == -5
|
||
assert data["data"]["logs"][0]["logMeta"] == "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}"
|
||
|
||
def test_get_upload_status_without_log_id():
|
||
"""测试不带 logId 参数查询"""
|
||
response = client.get("/watson/api/project/bs/upload?groupId=1000")
|
||
|
||
assert response.status_code == 200
|
||
data = response.json()
|
||
|
||
assert data["code"] == "200"
|
||
assert len(data["data"]["logs"]) == 0
|
||
|
||
def test_deterministic_data():
|
||
"""测试相同 logId 返回相同数据"""
|
||
response1 = client.get("/watson/api/project/bs/upload?groupId=1000&logId=13994")
|
||
response2 = client.get("/watson/api/project/bs/upload?groupId=1000&logId=13994")
|
||
|
||
log1 = response1.json()["data"]["logs"][0]
|
||
log2 = response2.json()["data"]["logs"][0]
|
||
|
||
# 验证关键字段相同（除了 fileUploadTime）
|
||
assert log1["logId"] == log2["logId"]
|
||
assert log1["bankName"] == log2["bankName"]
|
||
assert log1["accountNoList"] == log2["accountNoList"]
|
||
assert log1["enterpriseNameList"] == log2["enterpriseNameList"]
|
||
```
|
||
|
||
## 4. 实施要点
|
||
|
||
### 4.1 实施步骤
|
||
|
||
1. **修复 FileRecord 类**：修改 `log_meta` 默认值为正确的字符串格式
|
||
2. **重构 get_upload_status() 方法**：移除对 `self.file_records` 的依赖
|
||
3. **新增 _generate_deterministic_record() 方法**：实现确定性数据生成
|
||
4. **更新单元测试**：添加新的测试用例验证功能
|
||
5. **运行测试验证**：确保所有测试通过
|
||
|
||
### 4.2 注意事项
|
||
|
||
1. **随机种子**: 必须在生成数据前调用 `random.seed(log_id)`
|
||
2. **时间字段**: `fileUploadTime` 使用当前时间，每次调用会不同
|
||
3. **兼容性**: 不影响其他接口（上传、解析状态检查等）
|
||
4. **性能**: 无需优化，当前方案已足够高效
|
||
|
||
### 4.3 风险评估
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
|------|------|----------|
|
||
| 与上传接口数据不一致 | 低 | Mock 服务器允许独立数据源 |
|
||
| 随机种子冲突 | 极低 | logId 范围足够大（10000+） |
|
||
| 字段缺失 | 中 | 严格按文档生成 26 个字段 |
|
||
|
||
## 5. 验收标准
|
||
|
||
### 5.1 功能验收
|
||
|
||
- [ ] 带 logId 参数查询返回非空 logs 数组
|
||
- [ ] 不带 logId 参数查询返回空 logs 数组
|
||
- [ ] 相同 logId 多次查询返回相同的核心字段值
|
||
- [ ] 返回数据包含完整的 26 个字段
|
||
- [ ] status 字段值为 -5
|
||
- [ ] logMeta 字段中 balanceAmount 为字符串 "-1"
|
||
|
||
### 5.2 质量验收
|
||
|
||
- [ ] 所有单元测试通过
|
||
- [ ] 代码符合项目编码规范
|
||
- [ ] 无语法错误和运行时错误
|
||
- [ ] API 文档（Swagger UI）正确展示接口
|
||
|
||
### 5.3 文档验收
|
||
|
||
- [ ] CLAUDE.md 更新（如有必要）
|
||
- [ ] 代码注释完整清晰
|
||
- [ ] 测试用例覆盖所有场景
|
||
|
||
## 6. 后续优化建议
|
||
|
||
### 6.1 可选增强
|
||
|
||
1. **缓存机制**: 如需提高性能，可基于 logId 缓存生成结果
|
||
2. **更多银行类型**: 扩展银行类型和模板选项
|
||
3. **异常场景**: 支持通过特殊 logId 触发错误响应
|
||
|
||
### 6.2 不建议的优化
|
||
|
||
1. **关联上传记录**: 会增加复杂度，违背 Mock 服务器独立原则
|
||
2. **预生成数据池**: 过度设计，当前场景不需要
|
||
|
||
## 7. 参考资料
|
||
|
||
- 接口文档: `assets/兰溪-流水分析对接3.md` 第374-516行
|
||
- 当前实现: `services/file_service.py` 第265-300行
|
||
- FileRecord 模型: `services/file_service.py` 第12-59行
|