# dataSourcesApi

**Repository Path**: haoyanwei/data-sources-api

## Basic Information

- **Project Name**: dataSourcesApi
- **Description**: No description available
- **Primary Language**: Rust
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-12
- **Last Updated**: 2025-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据源 API 服务与任务管理系统

本项目是一个集成数据源管理和任务调度的全栈应用，包含FastAPI后端和Vue 3前端。系统支持多数据源集成（PostgreSQL、ClickHouse、CitusDB），提供任务管理、数据分析和数据同步功能。

## 目录结构

```
.
├── backend/             # 后端项目
│   ├── app/            # 应用代码
│   │   ├── api/       # API路由
│   │   ├── core/      # 核心配置
│   │   ├── db/        # 数据库配置
│   │   ├── models/    # 数据模型
│   │   ├── schemas/   # 数据验证模式
│   │   ├── services/  # 业务逻辑
│   │   └── utils/     # 工具函数
│   ├── tests/         # 测试代码
│   └── requirements.txt # 依赖包
├── frontend/           # 前端项目
│   ├── src/           # 源代码
│   │   ├── api/       # API请求
│   │   ├── assets/    # 静态资源
│   │   ├── components/# 组件
│   │   ├── router/    # 路由
│   │   ├── store/     # 状态管理
│   │   ├── styles/    # 样式
│   │   ├── utils/     # 工具函数
│   │   └── views/     # 页面
│   └── package.json   # 依赖配置
└── migrations/         # 数据库迁移文件
```

## 系统要求

### 后端要求
- Python 3.8+
- PostgreSQL 13+
- ClickHouse 22.3+
- CitusDB 11.0+

### 前端要求
- Node.js 16.0+
- npm 7.0+

## 安装部署指南

### 1. 后端部署

#### 1.1 环境准备
```bash
# 创建并激活虚拟环境
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
cd backend
pip install -r requirements.txt
```

#### 1.2 数据库配置
1. 安装并启动PostgreSQL、ClickHouse和CitusDB
2. 创建配置文件 `.env`：
```
# PostgreSQL配置
POSTGRES_SERVER=172.26.230.210  # 根据实际情况修改
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=task_management

# ClickHouse配置
CLICKHOUSE_SERVER=localhost
CLICKHOUSE_PORT=18123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=
CLICKHOUSE_DB=task_management

# CitusDB配置
CITUS_SERVER=localhost
CITUS_PORT=5432
CITUS_USER=postgres
CITUS_PASSWORD=postgres
CITUS_DB=task_management

# API配置
API_V1_STR=/api/v1
PROJECT_NAME=数据源API服务
```

#### 1.3 启动后端服务
```bash
cd backend
# 开发环境启动
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 生产环境启动
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

### 2. 前端部署

#### 2.1 环境准备
```bash
cd frontend
npm install
```

#### 2.2 开发环境启动
```bash
npm run dev
```

#### 2.3 生产环境构建与部署
```bash
# 构建生产版本
npm run build

# 部署dist目录到Web服务器
```

#### 2.4 Nginx配置（生产环境）
```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态资源
    location / {
        root /path/to/frontend/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # API代理
    location /api/v1 {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## API接口文档

### 认证与授权
本系统暂未实现认证机制，所有接口均可直接访问。

### 任务管理接口

#### 1. 获取任务列表
- **URL**: `/api/v1/tasks/`
- **方法**: `GET`
- **参数**:
  - `skip`: 跳过的记录数（默认0）
  - `limit`: 返回的最大记录数（默认100）
- **响应**:
```json
[
  {
    "id": 1,
    "title": "任务标题",
    "description": "任务描述",
    "status": "pending",
    "created_at": "2023-01-01T00:00:00",
    "updated_at": null,
    "user_id": null
  }
]
```

#### 2. 创建任务
- **URL**: `/api/v1/tasks/`
- **方法**: `POST`
- **请求体**:
```json
{
  "title": "任务标题",
  "description": "任务描述",
  "status": "pending"
}
```
- **响应**: 返回创建的任务对象

#### 3. 获取单个任务
- **URL**: `/api/v1/tasks/{task_id}`
- **方法**: `GET`
- **响应**: 返回指定ID的任务对象

#### 4. 更新任务
- **URL**: `/api/v1/tasks/{task_id}`
- **方法**: `PUT`
- **请求体**:
```json
{
  "title": "更新的标题",
  "description": "更新的描述",
  "status": "completed"
}
```
- **响应**: 返回更新后的任务对象

#### 5. 删除任务
- **URL**: `/api/v1/tasks/{task_id}`
- **方法**: `DELETE`
- **响应**: 204 No Content

### 数据分析接口

#### 1. 获取任务统计数据
- **URL**: `/api/v1/analytics/`
- **方法**: `GET`
- **响应**:
```json
{
  "total_tasks": 10,
  "completed_tasks": 5,
  "pending_tasks": 3,
  "in_progress_tasks": 2
}
```

## 使用指南

### 1. 前端页面导航

本系统采用左侧导航栏布局，主要包含以下功能页面：

#### 1.1 任务列表
- 显示所有任务
- 支持按状态筛选
- 支持排序和分页
- 提供任务操作按钮（编辑、删除）

#### 1.2 新建任务
- 提供任务创建表单
- 支持设置任务标题、描述和状态
- 提交后自动刷新任务列表

#### 1.3 数据分析
- 展示任务统计数据
- 提供数据可视化图表

### 2. 常见操作流程

#### 2.1 创建任务
1. 点击左侧导航栏的"新建任务"
2. 填写任务信息
3. 点击"提交"按钮

#### 2.2 编辑任务
1. 在任务列表中找到目标任务
2. 点击"编辑"按钮
3. 修改任务信息
4. 点击"保存"按钮

#### 2.3 删除任务
1. 在任务列表中找到目标任务
2. 点击"删除"按钮
3. 确认删除操作

## 故障排除

### 1. 后端服务启动问题

#### 1.1 数据库连接错误
- 检查数据库服务是否正常运行
- 验证连接参数是否正确
- 确认网络连接是否正常

#### 1.2 依赖包安装问题
- 确保使用正确的Python版本
- 尝试更新pip: `pip install --upgrade pip`
- 手动安装报错的依赖包

### 2. 前端问题

#### 2.1 API请求失败
- 检查后端服务是否正常运行
- 检查Vite代理配置是否正确
- 确认请求URL是否正确

#### 2.2 页面显示异常
- 清除浏览器缓存
- 检查控制台是否有错误信息
- 重新构建前端项目

### 3. 特定问题解决方案

#### 3.1 ClickHouse连接失败
目前系统已临时禁用ClickHouse同步功能，如需启用，请确认ClickHouse服务配置正确。

#### 3.2 前端API代理问题
如果出现IPv6连接问题，请修改`frontend/vite.config.js`中的代理配置，使用IPv4地址：
```js
proxy: {
  '/api/v1': {
    target: 'http://127.0.0.1:8000',
    changeOrigin: true,
    secure: false,
    ws: true
  }
}
```

## 开发指南

### 1. 后端开发

#### 1.1 添加新API端点
1. 在`backend/app/api/v1/endpoints/`目录下创建或修改路由文件
2. 在`backend/app/main.py`中注册路由
3. 实现相应的服务逻辑

#### 1.2 添加新数据模型
1. 在`backend/app/models/`目录下定义SQLAlchemy模型
2. 在`backend/app/schemas/`目录下定义Pydantic模式
3. 创建数据库迁移

### 2. 前端开发

#### 2.1 添加新页面
1. 在`frontend/src/views/`目录下创建Vue组件
2. 在`frontend/src/router/index.js`中添加路由配置
3. 更新导航菜单

#### 2.2 添加新API请求
1. 在`frontend/src/api/`目录下定义API函数
2. 在组件中导入并使用API函数

## 许可证

MIT License