396 lines
11 KiB
Markdown
396 lines
11 KiB
Markdown
# 下一步开发工作建议
|
||
|
||
**生成日期**: 2026-01-10
|
||
**基于**: 研发进度说明.md 和代码分析
|
||
|
||
---
|
||
|
||
## 📊 当前状态总结
|
||
|
||
### ✅ 已完成的工作
|
||
|
||
根据研发进度说明，**所有 7 个核心业务接口已全部完成（100%）**：
|
||
|
||
| 模块 | 接口数 | 完成度 |
|
||
|------|--------|--------|
|
||
| 数据盘点智能分析服务 | 4 个 | 100% ✅ |
|
||
| 场景挖掘智能推荐服务 | 2 个 | 100% ✅ |
|
||
| 数据资产盘点报告生成服务 | 1 个 | 100% ✅ |
|
||
|
||
### ⚠️ 技术债务与待改进项
|
||
|
||
根据研发进度说明和代码分析，发现以下待完成的工作：
|
||
|
||
---
|
||
|
||
## 🎯 优先级排序的开发任务
|
||
|
||
### 🔴 **高优先级**（影响生产环境使用）
|
||
|
||
#### 1. **补充缺失的单元测试** ⭐⭐⭐
|
||
**优先级**: 高
|
||
**工作量**: 8-10 人日
|
||
**状态**: 部分完成（5/8 接口有测试）
|
||
|
||
**当前测试覆盖情况**：
|
||
|
||
| 接口 | 测试文件 | 状态 |
|
||
|------|---------|------|
|
||
| `/api/v1/inventory/ai-analyze` | ✅ `test_ai_analyze.py` | 已测试 |
|
||
| `/api/v1/inventory/parse-document` | ❌ 缺失 | **需要补充** |
|
||
| `/api/v1/inventory/parse-sql-result` | ❌ 缺失 | **需要补充** |
|
||
| `/api/v1/inventory/parse-business-tables` | ❌ 缺失 | **需要补充** |
|
||
| `/api/v1/value/scenario-recommendation` | ✅ `test_scenario_recommendation.py` | 已测试 |
|
||
| `/api/v1/value/scenario-optimization` | ✅ `test_scenario_optimization.py` | 已测试 |
|
||
| `/api/v1/delivery/generate-report` | ✅ `test_report_generation.py` | 已测试 |
|
||
| `/api/v1/common/*` | ✅ `test_common.py` | 已测试 |
|
||
|
||
**需要补充的测试文件**：
|
||
|
||
1. **`tests/test_parse_document.py`** - 文档解析接口测试
|
||
- 测试 Excel/Word/PDF 文件解析
|
||
- 测试文件类型自动识别
|
||
- 测试错误处理（无效文件、文件损坏等）
|
||
- 测试表结构信息提取
|
||
|
||
2. **`tests/test_parse_sql_result.py`** - SQL 结果解析接口测试
|
||
- 测试 Excel/CSV 文件解析
|
||
- 测试编码识别（UTF-8、GBK等）
|
||
- 测试列名映射（中英文）
|
||
- 测试按表名分组
|
||
|
||
3. **`tests/test_parse_business_tables.py`** - 业务表解析接口测试
|
||
- 测试批量文件上传
|
||
- 测试多 Sheet 解析
|
||
- 测试进度反馈
|
||
- 测试部分文件失败时的处理
|
||
|
||
**建议**：
|
||
- 参考现有的测试文件（如 `test_ai_analyze.py`）的测试模式和结构
|
||
- 使用 `unittest.mock` 模拟文件操作和 LLM 调用
|
||
- 覆盖正常情况和异常情况
|
||
- 确保测试可以独立运行，不依赖外部资源
|
||
|
||
---
|
||
|
||
#### 2. **实现 SSE 流式响应** ⭐⭐⭐
|
||
**优先级**: 高
|
||
**工作量**: 6-8 人日
|
||
**状态**: 未实现
|
||
|
||
**影响**：
|
||
- LLM 响应时间较长（报告生成可能需要几分钟）
|
||
- 用户体验差（长时间等待无反馈）
|
||
- 前端无法显示实时进度
|
||
|
||
**需要实现流式响应的接口**：
|
||
|
||
1. **`/api/v1/inventory/ai-analyze`** - AI 分析接口
|
||
- 流式返回每个表的分析结果
|
||
- 显示处理进度（已完成 N/M 个表）
|
||
|
||
2. **`/api/v1/delivery/generate-report`** - 报告生成接口 ⭐
|
||
- 流式返回报告生成进度（章节一、二、三、四）
|
||
- 显示每个章节的生成状态
|
||
- 最终返回完整报告
|
||
|
||
3. **`/api/v1/value/scenario-recommendation`** - 场景推荐接口
|
||
- 流式返回推荐场景（逐个返回）
|
||
- 显示推荐进度
|
||
|
||
**技术实现**：
|
||
|
||
```python
|
||
from fastapi.responses import StreamingResponse
|
||
import json
|
||
|
||
@router.post("/ai-analyze-stream")
|
||
async def ai_analyze_stream(request: AIAnalyzeRequest):
|
||
"""流式返回 AI 分析结果"""
|
||
async def generate():
|
||
# 处理第一个表
|
||
result1 = await analyze_table(request.tables[0])
|
||
yield f"data: {json.dumps({'table': 1, 'result': result1})}\n\n"
|
||
|
||
# 处理第二个表
|
||
result2 = await analyze_table(request.tables[1])
|
||
yield f"data: {json.dumps({'table': 2, 'result': result2})}\n\n"
|
||
|
||
# 完成
|
||
yield f"data: {json.dumps({'status': 'completed'})}\n\n"
|
||
|
||
return StreamingResponse(
|
||
generate(),
|
||
media_type="text/event-stream"
|
||
)
|
||
```
|
||
|
||
**前端集成**：
|
||
|
||
```javascript
|
||
const eventSource = new EventSource('/api/v1/inventory/ai-analyze-stream');
|
||
|
||
eventSource.onmessage = (event) => {
|
||
const data = JSON.parse(event.data);
|
||
// 更新 UI，显示进度
|
||
updateProgress(data);
|
||
};
|
||
```
|
||
|
||
**工作量分解**：
|
||
- LLM 客户端支持流式调用：2 人日
|
||
- 报告生成接口流式响应：3 人日
|
||
- AI 分析接口流式响应：2 人日
|
||
- 场景推荐接口流式响应：1 人日
|
||
|
||
---
|
||
|
||
### 🟡 **中优先级**（提升系统质量和性能）
|
||
|
||
#### 3. **性能优化** ⭐⭐
|
||
**优先级**: 中
|
||
**工作量**: 5-7 人日
|
||
|
||
**优化方向**：
|
||
|
||
1. **LLM 调用优化**
|
||
- 批量处理（多个表/场景一起分析）
|
||
- 并发处理（使用 `asyncio.gather` 并行调用）
|
||
- 缓存优化（已实现 Redis 缓存，可进一步优化缓存策略）
|
||
|
||
2. **文件处理优化**
|
||
- 大文件分块处理
|
||
- 使用内存映射（mmap）处理大文件
|
||
- 异步文件 I/O
|
||
|
||
3. **数据库查询优化**（如果引入数据库）
|
||
- 索引优化
|
||
- 查询缓存
|
||
- 分页处理
|
||
|
||
**具体任务**：
|
||
|
||
- [ ] 分析当前接口性能瓶颈（使用 `time` 模块和日志）
|
||
- [ ] 优化 AI 分析接口（批量处理表）
|
||
- [ ] 优化报告生成接口（并行生成章节）
|
||
- [ ] 添加性能监控（响应时间、吞吐量）
|
||
|
||
---
|
||
|
||
#### 4. **数据库集成** ⭐⭐
|
||
**优先级**: 中
|
||
**工作量**: 10-12 人日
|
||
**状态**: 未开始（models 目录为空）
|
||
|
||
**需求分析**：
|
||
|
||
当前系统是**无状态 API**，所有数据都是通过请求传入的。引入数据库可以实现：
|
||
|
||
1. **数据持久化**
|
||
- 保存项目信息
|
||
- 保存盘点结果
|
||
- 保存报告历史
|
||
|
||
2. **数据查询和管理**
|
||
- 历史报告查询
|
||
- 项目数据管理
|
||
- 统计分析
|
||
|
||
**技术选型建议**：
|
||
|
||
- **ORM**: SQLAlchemy 2.0（异步支持）
|
||
- **数据库**: PostgreSQL（推荐）或 MySQL
|
||
- **迁移工具**: Alembic
|
||
|
||
**需要实现的模型**：
|
||
|
||
1. **项目模型**（Project）
|
||
```python
|
||
- id: UUID
|
||
- name: str
|
||
- industry: str
|
||
- created_at: datetime
|
||
- updated_at: datetime
|
||
```
|
||
|
||
2. **盘点结果模型**（InventoryResult）
|
||
```python
|
||
- id: UUID
|
||
- project_id: UUID
|
||
- tables: JSON (表列表)
|
||
- analysis_result: JSON (AI 分析结果)
|
||
- created_at: datetime
|
||
```
|
||
|
||
3. **报告模型**（Report）
|
||
```python
|
||
- id: UUID
|
||
- project_id: UUID
|
||
- report_content: JSON (报告内容)
|
||
- generated_at: datetime
|
||
```
|
||
|
||
**工作量分解**：
|
||
- 数据库设计和模型定义：2 人日
|
||
- ORM 集成和迁移：2 人日
|
||
- API 接口改造（支持数据持久化）：4 人日
|
||
- 数据查询接口：2 人日
|
||
- 测试和文档：2 人日
|
||
|
||
**注意**：数据库集成需要修改现有接口，建议：
|
||
- 保持向后兼容（支持无数据库模式）
|
||
- 分阶段实施（先实现数据持久化，再实现查询接口）
|
||
|
||
---
|
||
|
||
### 🟢 **低优先级**（可选功能）
|
||
|
||
#### 5. **其他改进建议** ⭐
|
||
|
||
1. **集成测试**
|
||
- 端到端测试
|
||
- API 集成测试
|
||
- 测试覆盖率统计（pytest-cov）
|
||
|
||
2. **文档完善**
|
||
- API 使用示例
|
||
- 部署文档
|
||
- 性能调优指南
|
||
|
||
3. **监控和运维**
|
||
- 健康检查完善
|
||
- 日志聚合（ELK 或其他）
|
||
- 告警规则优化
|
||
|
||
4. **安全加固**
|
||
- API 限流（ratelimit）
|
||
- 输入验证增强
|
||
- 安全审计日志
|
||
|
||
---
|
||
|
||
## 📋 推荐开发计划
|
||
|
||
### 第一阶段：质量保障（2-3 周）
|
||
|
||
**目标**：补充缺失的测试，确保系统稳定性
|
||
|
||
1. ✅ **补充缺失的单元测试**（8-10 人日）
|
||
- 文档解析接口测试（3 人日）
|
||
- SQL 结果解析接口测试（2 人日）
|
||
- 业务表解析接口测试（3 人日）
|
||
|
||
2. ✅ **完善测试配置**（1-2 人日）
|
||
- 添加 `pytest.ini` 配置文件
|
||
- 配置测试覆盖率报告
|
||
- 设置 CI/CD 测试流程（可选）
|
||
|
||
**成果**：
|
||
- 所有接口都有完整的单元测试
|
||
- 测试覆盖率 > 80%
|
||
- 可以通过 `pytest` 一键运行所有测试
|
||
|
||
---
|
||
|
||
### 第二阶段：用户体验提升（2-3 周）
|
||
|
||
**目标**：实现流式响应，提升用户体验
|
||
|
||
1. ✅ **实现 SSE 流式响应**（6-8 人日）
|
||
- LLM 客户端支持流式调用（2 人日）
|
||
- 报告生成接口流式响应（3 人日）
|
||
- AI 分析接口流式响应（2 人日）
|
||
- 前端对接示例（1 人日）
|
||
|
||
**成果**：
|
||
- 报告生成接口支持流式返回
|
||
- AI 分析接口支持流式返回
|
||
- 用户体验显著提升（有实时反馈）
|
||
|
||
---
|
||
|
||
### 第三阶段：系统增强（3-4 周）
|
||
|
||
**目标**：性能优化和数据库集成
|
||
|
||
1. ✅ **性能优化**（5-7 人日）
|
||
- LLM 调用并发优化（2 人日）
|
||
- 文件处理优化（2 人日）
|
||
- 性能监控（1 人日）
|
||
|
||
2. ✅ **数据库集成**（10-12 人日）
|
||
- 数据库设计和模型定义（2 人日）
|
||
- ORM 集成（2 人日）
|
||
- API 接口改造（4 人日）
|
||
- 数据查询接口（2 人日）
|
||
|
||
**成果**：
|
||
- 接口响应时间减少 30%+
|
||
- 支持数据持久化和历史查询
|
||
- 系统更加完整和可用
|
||
|
||
---
|
||
|
||
## 📊 工作量总计
|
||
|
||
| 阶段 | 任务 | 工作量（人日） |
|
||
|------|------|--------------|
|
||
| 第一阶段 | 补充单元测试 | 8-10 |
|
||
| 第二阶段 | 实现流式响应 | 6-8 |
|
||
| 第三阶段 | 性能优化 | 5-7 |
|
||
| 第三阶段 | 数据库集成 | 10-12 |
|
||
| **总计** | | **29-37 人日** |
|
||
|
||
**预计周期**：7-10 周（按 1 人开发计算）
|
||
|
||
---
|
||
|
||
## 🎯 立即开始的任务
|
||
|
||
根据当前状态，建议**立即开始**以下任务：
|
||
|
||
### 1. 补充缺失的单元测试
|
||
|
||
**为什么优先**：
|
||
- 测试是代码质量的保障
|
||
- 3 个接口完全没有测试，存在风险
|
||
- 测试编写相对独立，不会影响现有功能
|
||
|
||
**具体步骤**：
|
||
1. 创建 `tests/test_parse_document.py`
|
||
2. 创建 `tests/test_parse_sql_result.py`
|
||
3. 创建 `tests/test_parse_business_tables.py`
|
||
4. 运行 `pytest` 确保所有测试通过
|
||
|
||
### 2. 实现报告生成接口的流式响应
|
||
|
||
**为什么优先**：
|
||
- 报告生成是最耗时的操作（可能需要几分钟）
|
||
- 用户体验影响最大
|
||
- 技术实现相对清晰
|
||
|
||
**具体步骤**：
|
||
1. 改造 LLM 客户端支持流式调用
|
||
2. 修改报告生成服务支持流式返回
|
||
3. 更新 API 路由支持 SSE
|
||
4. 提供前端对接示例
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **保持向后兼容**：新功能不应该破坏现有接口
|
||
2. **分阶段实施**：不要一次性改动太多，分阶段迭代
|
||
3. **充分测试**：每个功能完成后都要进行充分测试
|
||
4. **更新文档**：代码变更后及时更新 API 文档和使用文档
|
||
|
||
---
|
||
|
||
## 📚 参考资源
|
||
|
||
- **FastAPI 流式响应文档**: https://fastapi.tiangolo.com/advanced/custom-response/#streamingresponse
|
||
- **Server-Sent Events (SSE) 规范**: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events
|
||
- **SQLAlchemy 异步文档**: https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html
|
||
- **pytest 最佳实践**: https://docs.pytest.org/en/stable/
|
||
|