finyxdata/开发工作计划.md

数据资源盘点系统 - 开发工作计划

📋 项目概述

本文档详细说明了数据资源盘点系统的开发工作计划，包括 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 秒）

---

📝 接口设计规范

统一响应格式

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  }
}

错误响应格式

{
  "success": false,
  "code": 400,
  "message": "错误信息",
  "error": {
    "error_code": "ERROR_CODE",
    "error_detail": "详细错误信息"
  }
}

分页响应格式

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "page_size": 20,
    "total_pages": 5
  }
}

---

🔐 环境变量配置

基础后端环境变量

# 应用配置
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