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

## 📋 项目概述

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