511 lines
15 KiB
Markdown
511 lines
15 KiB
Markdown
# 数据资源盘点系统 - 开发工作计划
|
||
|
||
## 📋 项目概述
|
||
|
||
本文档详细说明了数据资源盘点系统的开发工作计划，包括 AI 后端接口对接、基础后端服务开发以及前端功能实现。
|
||
|
||
**项目目标**：实现完整的数据资源盘点功能，包括数据导入、AI 智能分析、场景挖掘和报告生成。
|
||
|
||
---
|
||
|
||
## 🔍 现状分析
|
||
|
||
### 1. AI 后端接口情况（finyx_data_ai_backend）
|
||
|
||
#### ✅ 已实现接口
|
||
- `/api/v1/inventory/asset-detail` - 数据资产详情生成接口
|
||
- `/api/v1/delivery/generate-report` - 完整报告生成接口
|
||
- `/api/v1/delivery/export-report-pdf` - 导出报告 PDF 接口
|
||
- `/api/v1/common/health` - 健康检查
|
||
- `/api/v1/common/version` - 版本信息
|
||
|
||
#### ⏳ 待实现接口
|
||
- `/api/v1/inventory/parse-document` - 文档解析接口（方案一）
|
||
- `/api/v1/inventory/parse-sql-result` - SQL 结果解析接口（方案二）
|
||
- `/api/v1/inventory/parse-business-tables` - 业务表解析接口（方案三）
|
||
- `/api/v1/inventory/ai-analyze` - 数据资产智能识别接口（核心）
|
||
- `/api/v1/value/scenario-recommendation` - 潜在场景推荐接口
|
||
- `/api/v1/value/scenario-optimization` - 存量场景优化建议接口
|
||
|
||
### 2. 前端功能情况（finyx_data_frontend）
|
||
|
||
#### 已实现功能
|
||
- 项目列表管理（ProjectListView.vue）
|
||
- 项目作业流程（EngagementView.vue）
|
||
- 步骤一：上传数据资源表（InventoryStep.vue）
|
||
- 方案一：已有文档导入
|
||
- 方案二：IT 脚本提取
|
||
- 方案三：业务关键表导入
|
||
- 步骤二：背景调研（ContextStep.vue）
|
||
- 步骤三：识别场景（ValueStep.vue）
|
||
- 步骤四：盘点报告（DeliveryStep.vue）
|
||
- 数据资产详情页（DataAssetDetail.vue）
|
||
|
||
#### 需要对接的 API
|
||
- 项目 CRUD 接口
|
||
- 文件上传接口
|
||
- 数据解析接口（调用 AI 后端）
|
||
- AI 分析接口（调用 AI 后端）
|
||
- 场景推荐接口（调用 AI 后端）
|
||
- 报告生成接口（调用 AI 后端）
|
||
|
||
### 3. 基础后端情况（finyx_data_backend）
|
||
|
||
**当前状态**：目录存在但为空，需要从零开始创建。
|
||
|
||
**需要实现的功能**：
|
||
- 项目管理系统（CRUD）
|
||
- 文件上传和管理
|
||
- 与 AI 后端的接口代理/转发
|
||
- 数据持久化（数据库）
|
||
- 用户认证和权限管理（可选）
|
||
|
||
---
|
||
|
||
## 🎯 开发计划
|
||
|
||
### 阶段一：基础架构搭建（预计 3-5 天）
|
||
|
||
#### 1.1 项目初始化
|
||
- [ ] 创建 Python 项目结构（FastAPI）
|
||
- [ ] 配置依赖管理（requirements.txt）
|
||
- [ ] 设置环境变量配置（.env）
|
||
- [ ] 配置日志系统
|
||
- [ ] 配置数据库连接（PostgreSQL/MySQL）
|
||
|
||
#### 1.2 数据库设计
|
||
- [ ] 设计项目表（projects）
|
||
- id, name, client, status, progress, owner, created_at, updated_at
|
||
- [ ] 设计文件表（files）
|
||
- id, project_id, file_name, file_path, file_type, file_size, upload_time
|
||
- [ ] 设计数据资产表（data_assets）
|
||
- id, project_id, raw_name, ai_name, description, confidence, created_at
|
||
- [ ] 设计字段表（fields）
|
||
- id, asset_id, raw_name, ai_name, type, pii_type, is_important, confidence
|
||
- [ ] 设计场景表（scenarios）
|
||
- id, project_id, name, type, description, recommendation_index, selected
|
||
- [ ] 设计背景调研表（context_surveys）
|
||
- id, project_id, company_description, industry, data_scale, data_sources, platform_description
|
||
|
||
#### 1.3 基础服务层
|
||
- [ ] 实现数据库连接和会话管理
|
||
- [ ] 实现通用 CRUD 服务基类
|
||
- [ ] 实现文件上传服务
|
||
- [ ] 实现 AI 后端客户端（HTTP 客户端封装）
|
||
|
||
---
|
||
|
||
### 阶段二：项目管理和文件上传（预计 3-4 天）
|
||
|
||
#### 2.1 项目管理接口
|
||
- [ ] `POST /api/v1/projects` - 创建项目
|
||
- [ ] `GET /api/v1/projects` - 获取项目列表（支持分页、搜索）
|
||
- [ ] `GET /api/v1/projects/{id}` - 获取项目详情
|
||
- [ ] `PUT /api/v1/projects/{id}` - 更新项目
|
||
- [ ] `DELETE /api/v1/projects/{id}` - 删除项目
|
||
- [ ] `GET /api/v1/projects/{id}/progress` - 获取项目进度
|
||
|
||
#### 2.2 文件上传接口
|
||
- [ ] `POST /api/v1/projects/{id}/files/upload` - 上传文件
|
||
- 支持多文件上传
|
||
- 文件类型验证（Excel, Word, PDF, CSV）
|
||
- 文件大小限制（50MB）
|
||
- 文件存储路径管理
|
||
- [ ] `GET /api/v1/projects/{id}/files` - 获取项目文件列表
|
||
- [ ] `DELETE /api/v1/files/{id}` - 删除文件
|
||
- [ ] `GET /api/v1/files/{id}/download` - 下载文件
|
||
|
||
---
|
||
|
||
### 阶段三：数据解析接口对接（预计 5-7 天）
|
||
|
||
#### 3.1 文档解析接口（方案一）
|
||
- [ ] 实现 `POST /api/v1/inventory/parse-document` 代理接口
|
||
- 接收前端上传的文件
|
||
- 调用 AI 后端 `/api/v1/inventory/parse-document`
|
||
- 保存解析结果到数据库
|
||
- 返回解析结果给前端
|
||
|
||
#### 3.2 SQL 结果解析接口（方案二）
|
||
- [ ] 实现 `POST /api/v1/inventory/parse-sql-result` 代理接口
|
||
- 接收前端上传的 SQL 执行结果文件（Excel/CSV）
|
||
- 调用 AI 后端 `/api/v1/inventory/parse-sql-result`
|
||
- 保存解析结果到数据库
|
||
- 返回解析结果给前端
|
||
|
||
#### 3.3 业务表解析接口（方案三）
|
||
- [ ] 实现 `POST /api/v1/inventory/parse-business-tables` 代理接口
|
||
- 接收前端批量上传的业务表文件
|
||
- 调用 AI 后端 `/api/v1/inventory/parse-business-tables`
|
||
- 保存解析结果到数据库
|
||
- 返回解析结果给前端
|
||
|
||
**注意**：此阶段需要 AI 后端先实现对应的解析接口。
|
||
|
||
---
|
||
|
||
### 阶段四：AI 智能分析接口对接（预计 5-7 天）
|
||
|
||
#### 4.1 数据资产智能识别接口
|
||
- [ ] 实现 `POST /api/v1/inventory/ai-analyze` 代理接口
|
||
- 接收前端提交的表和字段数据
|
||
- 调用 AI 后端 `/api/v1/inventory/ai-analyze`
|
||
- 保存 AI 识别结果到数据库
|
||
- 返回识别结果给前端（包含 PII 识别、重要数据识别、置信度等）
|
||
|
||
#### 4.2 数据资产详情生成接口
|
||
- [ ] 实现 `POST /api/v1/inventory/asset-detail` 代理接口
|
||
- 接收资产 ID 或资产信息
|
||
- 调用 AI 后端 `/api/v1/inventory/asset-detail`
|
||
- 缓存生成的详情内容
|
||
- 返回详情数据给前端
|
||
|
||
---
|
||
|
||
### 阶段五：场景挖掘接口对接（预计 4-6 天）
|
||
|
||
#### 5.1 背景调研数据保存
|
||
- [ ] 实现 `POST /api/v1/projects/{id}/context` - 保存背景调研数据
|
||
- [ ] 实现 `GET /api/v1/projects/{id}/context` - 获取背景调研数据
|
||
|
||
#### 5.2 潜在场景推荐接口
|
||
- [ ] 实现 `POST /api/v1/value/scenario-recommendation` 代理接口
|
||
- 接收项目 ID 或背景调研数据
|
||
- 调用 AI 后端 `/api/v1/value/scenario-recommendation`
|
||
- 保存推荐场景到数据库
|
||
- 返回推荐场景列表给前端
|
||
|
||
#### 5.3 存量场景优化建议接口
|
||
- [ ] 实现 `POST /api/v1/value/scenario-optimization` 代理接口
|
||
- 接收存量场景列表
|
||
- 调用 AI 后端 `/api/v1/value/scenario-optimization`
|
||
- 保存优化建议
|
||
- 返回优化建议给前端
|
||
|
||
#### 5.4 场景管理接口
|
||
- [ ] `POST /api/v1/projects/{id}/scenarios/select` - 选择场景
|
||
- [ ] `GET /api/v1/projects/{id}/scenarios` - 获取项目场景列表
|
||
- [ ] `PUT /api/v1/scenarios/{id}` - 更新场景信息
|
||
|
||
---
|
||
|
||
### 阶段六：报告生成接口对接（预计 3-4 天）
|
||
|
||
#### 6.1 完整报告生成接口
|
||
- [ ] 实现 `POST /api/v1/delivery/generate-report` 代理接口
|
||
- 接收项目 ID 或报告数据
|
||
- 调用 AI 后端 `/api/v1/delivery/generate-report`
|
||
- 保存报告内容到数据库
|
||
- 返回报告数据给前端
|
||
|
||
#### 6.2 报告导出接口
|
||
- [ ] 实现 `POST /api/v1/delivery/export-report-pdf` 代理接口
|
||
- 接收报告 ID 或报告数据
|
||
- 调用 AI 后端 `/api/v1/delivery/export-report-pdf`
|
||
- 返回 PDF 文件流给前端
|
||
|
||
#### 6.3 报告管理接口
|
||
- [ ] `GET /api/v1/projects/{id}/report` - 获取项目报告
|
||
- [ ] `POST /api/v1/projects/{id}/report/regenerate` - 重新生成报告
|
||
|
||
---
|
||
|
||
### 阶段七：前端接口对接（预计 3-5 天）
|
||
|
||
#### 7.1 创建 API 客户端
|
||
- [ ] 在 `src/api/` 目录下创建 `inventory.ts`
|
||
- 项目管理 API
|
||
- 文件上传 API
|
||
- 数据解析 API
|
||
- AI 分析 API
|
||
- [ ] 在 `src/api/` 目录下创建 `scenario.ts`
|
||
- 场景推荐 API
|
||
- 场景优化 API
|
||
- 场景管理 API
|
||
- [ ] 在 `src/api/` 目录下创建 `report.ts`
|
||
- 报告生成 API
|
||
- 报告导出 API
|
||
|
||
#### 7.2 更新前端组件
|
||
- [ ] 更新 `ProjectListView.vue` - 对接项目列表 API
|
||
- [ ] 更新 `InventoryStep.vue` - 对接文件上传和解析 API
|
||
- [ ] 更新 `ContextStep.vue` - 对接背景调研保存 API
|
||
- [ ] 更新 `ValueStep.vue` - 对接场景推荐 API
|
||
- [ ] 更新 `DeliveryStep.vue` - 对接报告生成 API
|
||
- [ ] 更新 `DataAssetDetail.vue` - 对接资产详情 API
|
||
|
||
---
|
||
|
||
### 阶段八：测试和优化（预计 3-4 天）
|
||
|
||
#### 8.1 单元测试
|
||
- [ ] 编写后端服务层单元测试
|
||
- [ ] 编写 API 接口单元测试
|
||
- [ ] 编写前端组件单元测试
|
||
|
||
#### 8.2 集成测试
|
||
- [ ] 测试完整的数据导入流程
|
||
- [ ] 测试 AI 分析流程
|
||
- [ ] 测试场景推荐流程
|
||
- [ ] 测试报告生成流程
|
||
|
||
#### 8.3 性能优化
|
||
- [ ] 优化数据库查询（索引、查询优化）
|
||
- [ ] 实现接口缓存（Redis）
|
||
- [ ] 优化文件上传性能
|
||
- [ ] 优化前端加载性能
|
||
|
||
#### 8.4 错误处理和日志
|
||
- [ ] 完善错误处理机制
|
||
- [ ] 添加详细的日志记录
|
||
- [ ] 实现错误监控和告警
|
||
|
||
---
|
||
|
||
## 📁 目录结构设计
|
||
|
||
### finyx_data_backend 目录结构
|
||
|
||
```
|
||
finyx_data_backend/
|
||
├── app/
|
||
│ ├── __init__.py
|
||
│ ├── main.py # FastAPI 应用入口
|
||
│ ├── api/ # API 路由
|
||
│ │ ├── __init__.py
|
||
│ │ └── v1/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── projects.py # 项目管理接口
|
||
│ │ ├── files.py # 文件管理接口
|
||
│ │ ├── inventory.py # 数据盘点接口（代理 AI 后端）
|
||
│ │ ├── scenario.py # 场景挖掘接口（代理 AI 后端）
|
||
│ │ └── report.py # 报告生成接口（代理 AI 后端）
|
||
│ ├── core/ # 核心配置
|
||
│ │ ├── __init__.py
|
||
│ │ ├── config.py # 配置管理
|
||
│ │ ├── database.py # 数据库连接
|
||
│ │ ├── exceptions.py # 异常定义
|
||
│ │ └── response.py # 响应格式
|
||
│ ├── models/ # 数据库模型（SQLAlchemy）
|
||
│ │ ├── __init__.py
|
||
│ │ ├── project.py
|
||
│ │ ├── file.py
|
||
│ │ ├── data_asset.py
|
||
│ │ ├── field.py
|
||
│ │ ├── scenario.py
|
||
│ │ └── context_survey.py
|
||
│ ├── schemas/ # Pydantic 模型
|
||
│ │ ├── __init__.py
|
||
│ │ ├── project.py
|
||
│ │ ├── file.py
|
||
│ │ ├── inventory.py
|
||
│ │ ├── scenario.py
|
||
│ │ └── report.py
|
||
│ ├── services/ # 业务逻辑层
|
||
│ │ ├── __init__.py
|
||
│ │ ├── project_service.py
|
||
│ │ ├── file_service.py
|
||
│ │ ├── ai_client.py # AI 后端客户端
|
||
│ │ └── inventory_service.py
|
||
│ └── utils/ # 工具函数
|
||
│ ├── __init__.py
|
||
│ ├── logger.py
|
||
│ └── file_handler.py
|
||
├── tests/ # 测试目录
|
||
│ ├── __init__.py
|
||
│ ├── test_projects.py
|
||
│ ├── test_files.py
|
||
│ └── test_inventory.py
|
||
├── uploads/ # 上传文件目录
|
||
├── logs/ # 日志目录
|
||
├── .env # 环境变量（不提交到 Git）
|
||
├── .env.example # 环境变量示例
|
||
├── requirements.txt # Python 依赖
|
||
├── README.md # 项目说明
|
||
└── docker-compose.yml # Docker 编排（可选）
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 技术栈
|
||
|
||
### 后端技术栈
|
||
- **框架**：FastAPI
|
||
- **数据库**：PostgreSQL / MySQL
|
||
- **ORM**：SQLAlchemy
|
||
- **数据验证**：Pydantic
|
||
- **HTTP 客户端**：httpx / aiohttp（用于调用 AI 后端）
|
||
- **文件处理**：python-multipart
|
||
- **日志**：loguru
|
||
|
||
### AI 后端对接
|
||
- **协议**：HTTP REST API
|
||
- **格式**：JSON
|
||
- **超时设置**：根据接口复杂度设置（AI 分析接口可能需要 30-60 秒）
|
||
|
||
---
|
||
|
||
## 📝 接口设计规范
|
||
|
||
### 统一响应格式
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
// 具体数据
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误响应格式
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"code": 400,
|
||
"message": "错误信息",
|
||
"error": {
|
||
"error_code": "ERROR_CODE",
|
||
"error_detail": "详细错误信息"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 分页响应格式
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"items": [],
|
||
"total": 100,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"total_pages": 5
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 环境变量配置
|
||
|
||
### 基础后端环境变量
|
||
|
||
```bash
|
||
# 应用配置
|
||
APP_NAME=Finyx Data Backend
|
||
APP_VERSION=1.0.0
|
||
DEBUG=true
|
||
HOST=0.0.0.0
|
||
PORT=8001
|
||
|
||
# 数据库配置
|
||
DATABASE_URL=postgresql://user:password@localhost:5432/finyx_data
|
||
# 或 MySQL
|
||
# DATABASE_URL=mysql+pymysql://user:password@localhost:3306/finyx_data
|
||
|
||
# AI 后端配置
|
||
AI_BACKEND_URL=http://localhost:8000
|
||
AI_BACKEND_TIMEOUT=60
|
||
|
||
# 文件上传配置
|
||
UPLOAD_DIR=./uploads
|
||
MAX_FILE_SIZE=52428800 # 50MB
|
||
ALLOWED_EXTENSIONS=xlsx,xls,doc,docx,pdf,csv
|
||
|
||
# Redis 配置（可选，用于缓存）
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
REDIS_DB=0
|
||
REDIS_PASSWORD=
|
||
|
||
# 日志配置
|
||
LOG_LEVEL=INFO
|
||
LOG_DIR=./logs
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 开发步骤
|
||
|
||
### 第一步：创建基础后端项目
|
||
|
||
1. 在 `finyx_data_backend` 目录下创建项目结构
|
||
2. 初始化 Python 虚拟环境
|
||
3. 安装依赖包
|
||
4. 配置数据库
|
||
5. 创建基础模型和接口
|
||
|
||
### 第二步：实现项目管理功能
|
||
|
||
1. 创建项目模型和 Schema
|
||
2. 实现项目 CRUD 接口
|
||
3. 测试项目接口
|
||
|
||
### 第三步：实现文件上传功能
|
||
|
||
1. 创建文件模型
|
||
2. 实现文件上传接口
|
||
3. 实现文件管理接口
|
||
4. 测试文件上传
|
||
|
||
### 第四步：对接 AI 后端接口
|
||
|
||
1. 创建 AI 客户端服务
|
||
2. 实现数据解析接口代理
|
||
3. 实现 AI 分析接口代理
|
||
4. 实现场景推荐接口代理
|
||
5. 实现报告生成接口代理
|
||
|
||
### 第五步：前端接口对接
|
||
|
||
1. 创建前端 API 客户端
|
||
2. 更新前端组件调用 API
|
||
3. 处理错误和加载状态
|
||
4. 测试完整流程
|
||
|
||
---
|
||
|
||
## 📊 开发时间估算
|
||
|
||
| 阶段 | 预计时间 | 优先级 |
|
||
|------|---------|--------|
|
||
| 阶段一：基础架构搭建 | 3-5 天 | 高 |
|
||
| 阶段二：项目管理和文件上传 | 3-4 天 | 高 |
|
||
| 阶段三：数据解析接口对接 | 5-7 天 | 高 |
|
||
| 阶段四：AI 智能分析接口对接 | 5-7 天 | 高 |
|
||
| 阶段五：场景挖掘接口对接 | 4-6 天 | 中 |
|
||
| 阶段六：报告生成接口对接 | 3-4 天 | 中 |
|
||
| 阶段七：前端接口对接 | 3-5 天 | 高 |
|
||
| 阶段八：测试和优化 | 3-4 天 | 中 |
|
||
| **总计** | **29-42 天** | - |
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **AI 后端接口依赖**：部分功能需要等待 AI 后端接口实现完成
|
||
2. **文件存储**：需要考虑文件存储方案（本地存储或对象存储）
|
||
3. **性能优化**：AI 接口调用可能较慢，需要考虑异步处理和进度反馈
|
||
4. **错误处理**：需要完善的错误处理和用户友好的错误提示
|
||
5. **数据一致性**：确保基础后端和 AI 后端的数据一致性
|
||
6. **安全性**：文件上传需要验证文件类型和大小，防止恶意文件
|
||
|
||
---
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题或需要调整计划，请联系开发团队。
|
||
|
||
---
|
||
|
||
**文档版本**：v1.0.0
|
||
**创建日期**：2026-01-10
|
||
**最后更新**：2026-01-10
|