# Finyx Data AI - 接口可视化测试页面

## 📋 文档说明

本目录包含数据资产盘点系统各接口的可视化测试页面，提供完整的虚拟数据和交互测试功能，帮助开发人员和测试人员快速验证接口功能。

---

## 🚀 快速开始

### 1. 启动后端服务

```bash
cd /home/ubuntu/dev/finyx_data_ai
python -m app.main
```

服务将在 `http://localhost:8000` 启动。

### 2. 打开测试页面

直接在浏览器中打开以下 HTML 文件：

- **数据资产智能识别接口**: `test_ai_analyze.html`
- **文档解析接口**: `test_parse_document.html`
- **潜在场景推荐接口**: `test_scenario_recommendation.html`
- **完整报告生成接口**: `test_generate_report.html`

---

## 📊 测试页面列表

### 1. 数据资产智能识别接口测试 🔍

**文件名**: `test_ai_analyze.html`  
**接口路径**: `POST /api/v1/inventory/ai-analyze`  
**功能说明**: 使用大模型识别数据资产的中文名称、业务含义、PII敏感信息和重要数据特征

#### 功能特性

- ✅ 多行业虚拟数据支持（零售、金融、用户中心）
- ✅ 实时 PII 敏感信息识别
- ✅ 重要数据类型识别
- ✅ 置信度评分展示
- ✅ 可视化图表展示（PII分布、重要数据、置信度）
- ✅ 表结构折叠展示
- ✅ 字段详细信息卡片

#### 虚拟数据场景

| 场景 | 说明 | 核心数据 |
|------|------|----------|
| 零售场景 | 生鲜零售企业 | 用户信息、订单信息、会员信息 |
| 金融场景 | 银行机构 | 账户信息、交易记录 |
| 用户中心 | 用户管理系统 | 用户档案、登录日志、支付信息 |

#### 可视化图表

- **PII 敏感信息分布**: 柱状图展示各类敏感信息数量
- **重要数据类型分布**: 柱状图展示重要数据分类
- **置信度分布**: 柱状图展示识别置信度分布（高/中/低）

#### 统计卡片

- 总表数
- 总字段数
- PII 字段数
- 重要数据字段数
- 平均置信度

---

### 2. 文档解析接口测试 📄

**文件名**: `test_parse_document.html`  
**接口路径**: `POST /api/v1/inventory/parse-document`  
**功能说明**: 解析上传的数据字典文档（Excel/Word/PDF），提取表结构信息

#### 功能特性

- ✅ 支持文件拖拽上传
- ✅ 支持多文件上传
- ✅ 虚拟文件测试（Excel/Word/PDF）
- ✅ 文件类型识别
- ✅ 表结构提取展示
- ✅ 字段详细信息（类型、注释、主键、可为空）
- ✅ 文件大小格式化
- ✅ 解析耗时统计

#### 虚拟文件类型

| 文件类型 | 扩展名 | 虚拟数据 |
|---------|---------|----------|
| Excel | .xlsx, .xls | 用户信息表、订单信息表、商品信息表 |
| Word | .doc, .docx | 会员信息表 |
| PDF | .pdf | 交易流水表 |

#### 可视化图表

- **文件类型分布**: 柱状图展示不同文件类型数量
- **字段类型分布**: 柱状图展示字段类型分布（VARCHAR、INT、DECIMAL等）

#### 统计卡片

- 文件数
- 总表数
- 总字段数
- 解析耗时

---

### 3. 潜在场景推荐接口测试 💡

**文件名**: `test_scenario_recommendation.html`  
**接口路径**: `POST /api/v1/value/scenario-recommendation`  
**功能说明**: 基于企业背景、数据资产清单和存量场景，使用 AI 推荐潜在的数据应用场景

#### 功能特性

- ✅ 多行业场景支持（零售、金融、用户中心）
- ✅ 数据资产配置
- ✅ 存量场景管理（添加/删除）
- ✅ 推荐场景卡片展示
- ✅ 推荐指数星级评分
- ✅ 预估 ROI 标识
- ✅ 实施难度分级
- ✅ 依赖数据资产展示
- ✅ 技术要求清单

#### 虚拟场景数据

| 行业 | 推荐场景数 | 示例场景 |
|------|------------|----------|
| 零售 | 10个 | 精准会员营销、智能库存补货、价格弹性分析 |
| 金融 | 3个 | 智能风控、理财产品推荐、客户分群画像 |
| 用户中心 | 3个 | 用户行为分析、个性化推荐、用户增长预测 |

#### 场景类型

- **营销增长**: 精准营销、推荐、增长分析
- **降本增效**: 库存优化、损耗控制、智能客服
- **风险管理**: 风控、反欺诈
- **数据分析**: 行为分析、增长预测

#### 可视化图表

- **场景类型分布**: 柱状图展示不同类型场景数量
- **预估 ROI 分布**: 柱状图展示高/中/低 ROI 分布

#### 统计卡片

- 推荐场景数
- 高推荐指数（5星）
- 中等推荐指数（3-4星）
- 低推荐指数（1-2星）
- 生成耗时

---

### 4. 完整报告生成接口测试 📊

**文件名**: `test_generate_report.html`  
**接口路径**: `POST /api/v1/delivery/generate-report`  
**功能说明**: 基于数据盘点结果、背景调研信息和价值挖掘场景，生成完整的数据资产盘点工作总结报告

#### 功能特性

- ✅ 多行业报告模板（零售、金融、医疗）
- ✅ 四章节完整报告生成
- ✅ 报告导航快速定位
- ✅ 数据可视化展示
- ✅ 合规风险提示
- ✅ 专家建议列表
- ✅ 响应式报告布局

#### 报告章节

| 章节 | 内容 |
|------|------|
| 章节一 | 企业数字化情况简介（企业背景、信息化建设现状、业务流与数据流） |
| 章节二 | 数据资源统计（数据总量概览、存储分布、数据来源结构） |
| 章节三 | 数据资产情况盘点（资产概览、资产构成、合规风险提示） |
| 章节四 | 专家建议与下一步计划（合规整改建议、技术演进建议、价值深化建议） |

#### 虚拟报告数据

| 行业 | 数据量 | 核心资产数 | 合规风险数 |
|------|--------|------------|------------|
| 零售 | 58 PB | 2个 | 2个 |
| 金融 | 63 PB | 1个 | 1个 |
| 医疗 | 62 PB | 1个 | 1个 |

#### 可视化组件

- **存储分布**: 彩色条形图展示不同业务域的数据量和存储类型
- **数据来源结构**: 结构化数据 vs 半结构化数据比例
- **风险警告框**: 橙色警告框展示合规风险
- **建议列表**: 带序号的建议列表

---

## 🎨 通用功能

所有测试页面都包含以下通用功能：

### API 调用信息展示

- ✅ 请求端点显示
- ✅ 请求数据 JSON 格式化展示
- ✅ 响应数据 JSON 格式化展示
- ✅ 代码语法高亮

### 数据可视化

- ✅ 柱状图（Bar Chart）
- ✅ 饼图（Pie Chart）
- ✅ 卡片列表（Card List）
- ✅ 表格展示（Table）
- ✅ 统计卡片（Stat Cards）
- ✅ 标签展示（Tags）

### UI/UX 特性

- ✅ 加载状态展示（动画 Spinner）
- ✅ 成功/错误消息提示
- ✅ Toast 消息通知
- ✅ 表单验证
- ✅ 响应式布局（支持桌面/平板/手机）
- ✅ 深色/浅色配色方案
- ✅ 平滑动画过渡

### 虚拟数据功能

- ✅ 快速加载虚拟数据按钮
- ✅ 多场景数据支持
- ✅ 动态数据生成
- ✅ 模拟 API 响应

---

## 🛠️ 技术架构

### 基础框架

所有测试页面共享以下基础框架：

#### 1. `base_test_framework.js` - JavaScript 框架

提供以下功能：

**API 调用函数**
- `apiRequest(endpoint, data, method)` - 统一的 API 请求函数
- `showLoading(elementId)` - 显示加载状态
- `hideLoading(elementId, content)` - 隐藏加载状态
- `showError(elementId, message)` - 显示错误信息
- `showSuccess(elementId, message)` - 显示成功消息

**图表渲染函数**
- `renderBarChart(containerId, data, title)` - 渲染柱状图
- `renderPieChart(containerId, data, title)` - 渲染饼图
- `renderCardList(containerId, items, title)` - 渲染卡片列表
- `renderTable(containerId, columns, data, title)` - 渲染表格

**辅助函数**
- `getBarColor(index)` - 获取柱状图颜色
- `formatCellValue(value)` - 格式化单元格值
- `formatNumber(num, decimals)` - 格式化数字
- `formatTime(seconds)` - 格式化时间
- `delay(ms)` - 延迟函数
- `copyToClipboard(text)` - 复制到剪贴板
- `showToast(message)` - 显示 Toast 消息

#### 2. `test_common.css` - 公共样式

提供以下样式：

**布局组件**
- 容器（`.container`）
- 栅格布局（`.content-grid`）
- 卡片（`.card`）
- 标题（`.page-title`, `.section-title`）

**表单组件**
- 输入框（`.form-control`）
- 按钮（`.btn`）
- 表单组（`.form-group`）
- 表单行（`.form-row`）

**数据展示**
- 统计卡片（`.stat-card`）
- 表格（`.data-table`）
- 标签（`.tag`）
- 选项卡（`.tabs`）

**状态反馈**
- 加载动画（`.spinner`）
- 错误容器（`.error-container`）
- 成功容器（`.success-container`）
- Toast 消息（`.toast`）

**响应式设计**
- 桌面端（> 992px）
- 平板端（768px - 992px）
- 移动端（< 768px）

---

## 📝 使用指南

### 基本使用流程

1. **选择测试页面**
   - 根据需要测试的接口，打开对应的 HTML 文件

2. **配置测试参数**
   - 填写表单字段
   - 或点击"快速使用虚拟数据"按钮

3. **执行测试**
   - 点击"开始分析"/"生成推荐"/"生成报告"等按钮
   - 等待模拟 API 调用完成

4. **查看结果**
   - 查看统计卡片了解概览
   - 查看图表了解数据分布
   - 查看详细信息了解具体结果

5. **查看 API 数据**
   - 在左侧面板查看请求数据
   - 查看响应数据的 JSON 格式

### 高级使用

#### 自定义虚拟数据

每个测试页面都提供了 `mockData` 对象，可以根据需要修改：

```javascript
const mockData = {
    // 自定义数据结构
};
```

#### 连接真实 API

修改 `API_BASE_URL` 常量，连接到实际后端：

```javascript
const API_BASE_URL = 'http://localhost:8000/api/v1';
```

然后移除模拟 API 调用代码，使用真实的 `apiRequest()` 函数。

---

## 🐛 常见问题

### Q1: 页面无法显示图表？

**A**: 确保 `base_test_framework.js` 和 `test_common.css` 文件与 HTML 文件在同一目录下。

### Q2: 虚拟数据不符合我的需求？

**A**: 可以直接修改 HTML 文件中的 `mockData` 对象，自定义虚拟数据。

### Q3: 如何连接到真实后端 API？

**A**: 
1. 确保后端服务已启动
2. 修改 `API_BASE_URL` 为实际后端地址
3. 移除模拟响应代码，使用 `apiRequest()` 函数

### Q4: 如何添加新的测试场景？

**A**: 
1. 复制现有测试页面作为模板
2. 修改页面标题和描述
3. 自定义虚拟数据和表单字段
4. 调整渲染函数以适配新接口

---

## 📦 文件结构

```
tests/
├── README.md                              # 本文档
├── base_test_framework.js                  # JavaScript 基础框架
├── test_common.css                         # 公共样式文件
├── test_ai_analyze.html                   # 数据资产智能识别接口测试
├── test_parse_document.html               # 文档解析接口测试
├── test_scenario_recommendation.html       # 潜在场景推荐接口测试
└── test_generate_report.html             # 完整报告生成接口测试
```

---

## 🎯 下一步计划

### 待开发的测试页面

- [ ] SQL 结果解析接口测试页面
- [ ] 业务表解析接口测试页面
- [ ] 存量场景优化建议接口测试页面

### 功能增强

- [ ] 添加单元测试自动化
- [ ] 添加性能测试
- [ ] 添加对比测试（多个模型对比）
- [ ] 添加测试报告导出功能
- [ ] 添加测试数据持久化

---

## 📞 联系方式

如有问题或建议，请联系：

- **项目负责人**: [待填写]
- **技术负责人**: [待填写]
- **测试负责人**: [待填写]

---

## 📄 相关文档

- [接口开发文档索引](../docs/README.md)
- [API 概览](../API_OVERVIEW.md)
- [开发指南](../DEVELOPMENT.md)
- [快速开始](../QUICK_START.md)

---

**最后更新**: 2026-01-11  
**版本**: v1.0.0  
**维护者**: Finyx AI Team