2478 Proposal E3873265

# Proposal: Add Plugin Data Explorer

## Change ID
`add-plugin-data-explorer`

## Summary
新增一个独立的"数据浏览器"页面，允许用户基于插件配置动态浏览对应数据库表的数据，并支持 SQL 层面的自定义查询。

## Background

### 现状分析
1. **已有功能**：
   - 每个插件的 `schema.json` 定义了 `table_name` 和列信息
   - `/api/datamanage/plugins/{name}/data` 接口支持按插件名获取数据预览
   - `PluginDataDialog.vue` 弹窗组件实现基础的数据浏览（仅支持日期筛选和分页）
   - 数据库使用 ClickHouse，支持高性能 SQL 查询

2. **局限性**：
   - 当前数据预览是弹窗形式，空间有限
   - 仅支持简单的日期筛选，无法进行复杂查询
   - 无法跨表查询或使用 SQL 聚合函数
   - 无法导出查询结果

## Goals
1. 提供一个独立的"数据浏览器"页面，不再依赖弹窗
2. 支持基于插件的表结构动态生成列显示
3. 支持 SQL 查询模式，允许用户编写自定义查询
4. 提供查询结果的导出功能（CSV/Excel）
5. 保存常用查询模板

## Non-Goals
- 不支持数据写入/修改操作（只读查询）
- 不支持跨数据库查询（仅限 ClickHouse）
- 不替代专业的 BI 工具
- **不支持查询结果的图表可视化**（仅表格展示）

## Proposed Solution

### 架构概览

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        数据浏览器页面                                     │
├─────────────────────────────────────────────────────────────────────────┤
│  [插件选择器]  [快速筛选: 表名/分类]                                       │
├──────────────────────────────┬──────────────────────────────────────────┤
│  📋 表列表                    │  📊 数据浏览区域                           │
│  ├─ 📁 A股数据               │  ┌──────────────────────────────────────┐ │
│  │   ├─ ods_daily            │  │ 模式切换: [简单筛选] [SQL查询]        │ │
│  │   ├─ ods_daily_basic      │  ├──────────────────────────────────────┤ │
│  │   └─ ods_adj_factor       │  │                                      │ │
│  ├─ 📁 指数数据              │  │  【简单筛选模式】                       │ │
│  │   ├─ ods_index_daily      │  │  日期范围: [____] ~ [____]            │ │
│  │   └─ ods_index_basic      │  │  代码筛选: [____________]             │ │
│  └─ 📁 ETF数据               │  │  排序: [列名▼] [升序/降序]             │ │
│      └─ ods_etf_fund_daily   │  │                                      │ │
│                              │  │  【SQL查询模式】                       │ │
│  表信息:                      │  │  ┌────────────────────────────────┐  │ │
│  行数: 12,345,678            │  │  │ SELECT * FROM ods_daily        │  │ │
│  列数: 15                    │  │  │ WHERE ts_code = '000001.SZ'    │  │ │
│  分区: toYYYYMM(trade_date)  │  │  │ ORDER BY trade_date DESC       │  │ │
│                              │  │  │ LIMIT 100                      │  │ │
│  [查看表结构]                 │  │  └────────────────────────────────┘  │ │
│                              │  │  [运行查询] [格式化] [保存模板]        │ │
│                              │  ├──────────────────────────────────────┤ │
│                              │  │ 查询结果 (100 条/共 5,234 条)         │ │
│                              │  │ ┌────┬────────┬────────┬─────┬─────┐ │ │
│                              │  │ │代码│ 日期   │ 开盘价 │最高 │最低 │ │ │
│                              │  │ ├────┼────────┼────────┼─────┼─────┤ │ │
│                              │  │ │... │  ...   │  ...   │ ... │ ... │ │ │
│                              │  │ └────┴────────┴────────┴─────┴─────┘ │ │
│                              │  │ [导出CSV] [导出Excel]   分页: < 1 > │ │ │
│                              │  └──────────────────────────────────────┘ │
└──────────────────────────────┴──────────────────────────────────────────┘
```

### 核心功能

#### 1. 表列表面板
- 从所有已注册插件的 `schema.json` 读取表信息
- 按分类（A股/指数/ETF/其他）分组展示
- 显示表的基础信息（行数、列数、分区方式）
- 支持搜索过滤

#### 2. 简单筛选模式
- 日期范围选择器
- 股票代码筛选（支持模糊搜索）
- 列排序
- 分页浏览

#### 3. SQL 查询模式
- **多 Tab SQL 编辑器**（支持同时编辑多个查询）
- SQL 语法高亮
- 表名/列名自动补全
- 查询执行与结果展示
- 查询模板保存/加载
- **查询历史记录（前端 localStorage 存储）**

#### 4. 安全控制
- 只允许 SELECT 语句
- 限制查询返回行数（最大 10000 行）
- 限制查询执行时间（最大 30 秒）
- 管理员可配置 SQL 白名单/黑名单

### API 设计

```
# 获取所有可查询的表列表
GET /api/datamanage/tables
Response: { tables: [{ plugin_name, table_name, category, columns, row_count }] }

# 获取表结构详情
GET /api/datamanage/tables/{table_name}/schema
Response: { table_name, columns, partition_by, order_by, engine, comment }

# 简单查询（筛选模式）
POST /api/datamanage/tables/{table_name}/query
Body: { filters: {...}, sort_by, sort_order, page, page_size }

# SQL 查询
POST /api/datamanage/sql/execute
Body: { sql: "SELECT ...", max_rows: 1000 }
Response: { columns, data, row_count, execution_time }

# 导出查询结果
POST /api/datamanage/sql/export
Body: { sql: "SELECT ...", format: "csv" | "xlsx" }
Response: 文件流

# 查询模板管理
GET    /api/datamanage/sql/templates
POST   /api/datamanage/sql/templates
DELETE /api/datamanage/sql/templates/{id}
```

## Affected Components

### Backend
- `src/stock_datasource/modules/datamanage/router.py` - 新增 API 端点
- `src/stock_datasource/modules/datamanage/service.py` - 新增查询服务
- `src/stock_datasource/modules/datamanage/schemas.py` - 新增数据模型
- `src/stock_datasource/modules/datamanage/sql_validator.py` - SQL 安全校验（新文件）

### Frontend
- `frontend/src/views/datamanage/DataExplorerView.vue` - 新页面（新文件）
- `frontend/src/views/datamanage/components/TableListPanel.vue` - 表列表组件（新文件）
- `frontend/src/views/datamanage/components/SqlEditorTabs.vue` - 多 Tab SQL 编辑器组件（新文件）
- `frontend/src/views/datamanage/components/QueryResultTable.vue` - 查询结果表格（新文件）
- `frontend/src/api/datamanage.ts` - 新增 API 方法
- `frontend/src/router/index.ts` - 新增路由（作为数据管理的子路由）
- `frontend/src/composables/useQueryHistory.ts` - 查询历史记录 composable（新文件）

## Security Considerations

1. **SQL 注入防护**
   - 使用参数化查询
   - SQL 语句白名单校验（只允许 SELECT）
   - 禁止危险关键字（DROP, DELETE, INSERT, UPDATE, TRUNCATE 等）

2. **资源限制**
   - 查询超时限制（30 秒）
   - 返回行数限制（10000 行）
   - 并发查询数限制

3. **权限控制**
   - SQL 查询模式需要管理员权限
   - 简单筛选模式对所有用户开放

## Alternatives Considered

1. **使用现有弹窗扩展**
   - 优点：改动小
   - 缺点：空间受限，无法支持复杂查询
   
2. **集成第三方 BI 工具（如 Metabase）**
   - 优点：功能丰富
   - 缺点：增加部署复杂度，与现有系统集成困难

3. **仅提供 API，让用户用其他工具查询**
   - 优点：最简单
   - 缺点：用户体验差

## Implementation Plan

参见 `tasks.md`

## Decisions Made

1. **不支持**查询结果的图表可视化（仅表格展示）
2. SQL 编辑器**支持多 Tab**，可同时编辑多个查询
3. 查询历史记录**在前端 localStorage 保存**，无需后端存储
4. 数据浏览器作为**数据管理的二级菜单**，路由为 `/datamanage/explorer`