# wbr-data-hub-project

**Repository Path**: work_project_item/wbr-data-hub-project

## Basic Information

- **Project Name**: wbr-data-hub-project
- **Description**: 数据平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-18
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## WBR Data Hub Project

基于 FastAPI 的后端和 React + TypeScript + Vite 的前端示例工程，演示通过 REST API 进行前后端对接。

### 目录结构

- `backend/`：Python FastAPI 后端服务  
- `frontend/`：React + TypeScript + Vite 前端项目

### 环境要求

- Python 3.10 或以上版本  
- Node.js 18 或以上版本（建议包含 npm 或 pnpm）

### 后端（backend）

#### 安装依赖

```bash
cd backend
pip install -r requirements.txt
```

#### MySQL 数据库配置

- 后端已集成 MySQL（使用 SQLAlchemy + PyMySQL）
- 默认连接配置在 `app/core/config.py` 中，可通过环境变量覆盖：
  - `MYSQL_USER`
  - `MYSQL_PASSWORD`
  - `MYSQL_HOST`
  - `MYSQL_PORT`
  - `MYSQL_DB`

示例本地开发配置（仅示意，建议改成你自己的账号密码与数据库名）：

```bash
set MYSQL_USER=root
set MYSQL_PASSWORD=your_password
set MYSQL_HOST=127.0.0.1
set MYSQL_PORT=3306
set MYSQL_DB=wbr_data_hub
```

数据库连接测试接口：

- `GET http://localhost:8000/api/db-ping`
  - 正常返回 `code: 0` 且 `ping_result: 1` 表示 MySQL 连接成功

#### 初始化数据库和默认用户

后端服务启动时会自动：
- 创建数据库表（如果不存在）
- 初始化默认用户（账号：`root`，密码：`rma@new123`）

也可以手动执行初始化：

```bash
cd backend
# 初始化数据库表
python -m app.db.init_db
# 初始化默认用户（如果用户已存在则跳过）
python -m app.db.init_user
```

#### 启动开发服务

```bash
cd backend
python main.py
```

启动后：

- 健康检查接口：`GET http://localhost:8000/health`  
- 示例接口：`GET http://localhost:8000/api/example`

返回统一结构：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "project": "WBR Data Hub Backend",
    "example_value": "Hello from FastAPI backend"
  }
}
```

### 前端（frontend）

#### 安装依赖

```bash
cd frontend
npm install
```

#### 启动开发服务

```bash
cd frontend
npm run dev
```

默认运行在 `http://localhost:5173`。

在开发环境下，`vite.config.ts` 已配置代理：

- 前端访问 `/api/...` 会自动转发到 `http://localhost:8000/api/...`

#### 登录功能

前端已集成登录页面和认证机制：

- **登录页面**：`/login` 路径
- **路由保护**：所有业务页面需要登录后才能访问，未登录会自动跳转到登录页
- **Token管理**：登录成功后，token会保存到localStorage（仅用于前端状态管理）
- **登出功能**：点击页面右上角的用户菜单，可以选择退出登录

**注意**：后端API不需要token校验，HTTP客户端不会自动在请求头中添加token参数。

**登录接口**：
- 接口路径：`POST /api/auth/login`
- 请求体：`{ "username": "用户名", "password": "密码" }`
- 响应格式：
  ```json
  {
    "code": 0,
    "message": "ok",
    "data": {
      "token": "TOKEN_STRING",
      "user": {
        "username": "用户名"
      }
    }
  }
  ```
  
  默认账号：`admin`，密码：`rma@new123`（首次启动服务时会自动创建）
  
  注意：token仅用于前端状态管理，后端API不会验证token。

### 示例前后端联调流程

1. 在 `backend` 目录启动 FastAPI 服务：  
   `uvicorn app.main:app --reload --port 8000`
2. 在 `frontend` 目录启动 Vite 前端：  
   `npm run dev`
3. 打开浏览器访问 `http://localhost:5173`：  
   - 未登录时会自动跳转到登录页面 `/login`
   - 输入用户名和密码进行登录（需要后端提供登录接口）
   - 登录成功后可以访问各个业务页面

### 功能模块

### Docker 开发环境部署

项目支持使用 Docker 进行开发环境部署，可以快速启动后端服务和 MySQL 数据库。

#### 前置要求

- Docker 和 Docker Compose 已安装
- Linux 系统（Windows 可使用 WSL2 或 Docker Desktop）

#### 快速开始

1. **配置环境变量**

```bash
# 复制环境变量示例文件
cp backend/docker/env.example backend/docker/.env

# 编辑 backend/docker/.env 文件，修改数据库配置
# MYSQL_USER=root
# MYSQL_PASSWORD=your_password
# MYSQL_HOST=mysql
# MYSQL_PORT=3306
# MYSQL_DB=wbr_data_hub
# MYSQL_ROOT_PASSWORD=rootpassword
```

2. **启动开发环境**

```bash
# 使用便捷脚本（推荐，在 backend 目录下执行）
cd backend
chmod +x scripts/dev-start.sh
./scripts/dev-start.sh

# 或手动执行（在 backend/docker 目录下）
cd backend/docker
docker-compose up -d --build
```

3. **初始化数据库（首次部署）**

```bash
# 使用便捷脚本（在 backend 目录下执行）
cd backend
chmod +x scripts/dev-init-db.sh
./scripts/dev-init-db.sh

# 或手动执行
cd backend/docker
docker-compose exec backend python -m app.db.init_db
docker-compose exec backend python -m app.db.init_user
```

4. **验证服务**

```bash
# 检查服务状态
cd backend/docker && docker-compose ps

# 测试健康检查接口
curl http://localhost:8001/health

# 查看日志（在 backend 目录下）
cd backend
./scripts/dev-logs.sh backend
```

#### 常用命令

```bash
# 在 backend 目录下执行
cd backend

# 启动服务
./scripts/dev-start.sh

# 停止服务
./scripts/dev-stop.sh

# 查看日志
./scripts/dev-logs.sh backend

# 初始化数据库
./scripts/dev-init-db.sh

# 进入后端容器（手动执行）
cd backend/docker
docker-compose exec backend bash

# 重启服务（手动执行）
cd backend/docker
docker-compose restart backend

# 重新构建镜像（手动执行）
cd backend/docker
docker-compose build --no-cache backend
```

#### 开发环境特性

- **代码热重载**：修改后端代码后，容器会自动重启（使用 `--reload` 参数）
- **代码挂载**：本地代码目录挂载到容器，修改立即生效
- **实时日志**：使用 `PYTHONUNBUFFERED=1` 确保日志实时输出
- **MySQL 容器**：自动启动 MySQL 8.0 容器，无需单独安装

#### 服务地址

- 后端API：`http://localhost:8001`
- 健康检查：`http://localhost:8001/health`
- MySQL：`localhost:3306`（容器内服务名为 `mysql`）

#### 注意事项

- 所有 Docker 相关配置文件统一放在 `backend/docker/` 目录下，与后端代码在一起
- 首次启动需要等待 MySQL 健康检查通过（约 30 秒）
- 开发环境代码通过 volume 挂载，修改代码无需重新构建镜像
- 数据库数据存储在 Docker volume 中，删除容器不会丢失数据（除非使用 `docker-compose down -v`）
- 详细说明请参考 `backend/docker/README.md`

### 后续扩展建议

- 后端可在 `app/api/` 下按业务模块拆分文件（如 `items.py`、`users.py`），并在 `routes.py` 中统一注册路由。  
- 前端可在 `src/` 下增加 `pages/`、`components/`、`services/` 等目录，逐步扩展页面以及与后端的交互逻辑。  
- 如果后续需要数据库、鉴权等功能，可以在当前骨架基础上迭代，不需要重构整体工程结构。