# jbm-weather

**Repository Path**: numen06/jbm-weather

## Basic Information

- **Project Name**: jbm-weather
- **Description**: 获取天气的API
....
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 天气API系统

基于FastAPI和Vue 3的天气API系统，使用Open-Meteo API提供历史、当前和预报天气数据。

## 功能特性

- 超级管理员后台管理（用户管理、API Key管理）
- API Key认证机制
- 三种天气查询模式：当前天气、天气预报、历史天气
- 免认证的省/市/区县开放 API，支持联动 JSON 与坐标匹配
- 基于Tabler的现代化UI界面

## 技术栈

### 后端
- FastAPI
- SQLAlchemy
- SQLite（可配置为PostgreSQL）
- JWT Token认证
- Open-Meteo API集成

### 前端
- Vue 3
- Vite
- Vue Router
- Tabler CSS
- Axios

## 快速开始

### 后端设置

1. 进入后端目录：
```bash
cd backend
```

2. 创建虚拟环境（推荐）：
```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
```

3. 安装依赖：
```bash
pip install -r requirements.txt
```

4. 配置环境变量（可选）：
```bash
cp .env.example .env
# 编辑.env文件修改配置
```

5. 初始化超级管理员（首次运行）：
```bash
python -c "from app.main import app; from app.database import engine, Base; from app.routers.admin import router; Base.metadata.create_all(bind=engine)"
```

或者直接运行应用，然后访问 `/api/admin/init` 端点初始化超级管理员。

6. 启动服务器：
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 前端设置

1. 进入前端目录：
```bash
cd frontend
```

2. 安装依赖：
```bash
npm install
```

3. 启动开发服务器：
```bash
npm run dev
```

前端将在 http://localhost:5173 运行

## 使用说明

### 超级管理员

1. 首次使用需要初始化超级管理员：
   - 访问后端API：`POST http://localhost:8000/api/admin/init`
   - 或使用默认配置（admin/admin123）

2. 登录管理后台：
   - 访问 http://localhost:5173/admin/login
   - 使用超级管理员账号登录

3. 创建用户和API Key：
   - 在用户管理页面创建新用户
   - 为用户创建API Key
   - 复制API Key提供给用户

### 普通用户

1. 访问天气查询页面：
   - 访问 http://localhost:5173/weather

2. 设置API Key：
   - 在API Key输入框中输入管理员分配的API Key

3. 查询天气：
   - 选择查询类型（当前/预报/历史）
   - 输入经纬度坐标
   - 点击查询按钮

## API文档

启动后端服务后，可以访问：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### 行政区开放 API

行政区接口无需 API Key，默认使用系统内置的 34 个省级区域行政区数据：

```text
GET /api/locations/provinces
GET /api/locations/cities?province=110000
GET /api/locations/districts?province=110000&city=110100
GET /api/locations/tree
GET /api/locations/search?q=海淀
GET /api/locations/resolve?longitude=116.304&latitude=39.966&coordinate_system=wgs84
```

`tree` 可直接作为省市区县级联组件的 JSON 数据源。坐标中心点同时返回
`gcj02` 和 `wgs84`；`resolve` 支持传入 `wgs84`、`gcj02` 或 `bd09`，返回最近的
区县中心点。该匹配是中心点近邻计算，不等同于基于行政边界的逆地理编码。

## 项目结构

```
jbm-weather/
├── backend/              # FastAPI后端
│   ├── app/
│   │   ├── routers/      # 路由
│   │   ├── services/     # 服务层
│   │   └── ...
│   └── requirements.txt
├── frontend/             # Vue前端
│   ├── src/
│   │   ├── views/        # 页面组件
│   │   ├── components/   # 通用组件
│   │   └── ...
│   └── package.json
└── README.md
```

## 环境变量

后端环境变量（.env文件）：
- `DATABASE_URL`: 数据库连接URL
- `JWT_SECRET_KEY`: JWT密钥
- `SUPER_ADMIN_USERNAME`: 超级管理员用户名（初始化用）
- `SUPER_ADMIN_PASSWORD`: 超级管理员密码（初始化用）
- `OPEN_METEO_BASE_URL`: Open-Meteo API基础URL
- `BAIDU_MAP_AK`: 百度地图服务端AK，用于 `/api/locations/ip` 的IP定位

`GET /api/locations/ip` 使用项目 API Key 认证，并优先按百度返回的六位 `adcode` 匹配本地省、市、区县编码。

前端环境变量（.env文件）：
- `VITE_API_BASE_URL`: 后端API地址（默认：http://localhost:8000）

## 注意事项

- Open-Meteo API是免费的，不需要API Key
- 默认使用SQLite数据库，生产环境建议使用PostgreSQL
- 首次运行会自动创建数据库表
- API Key请妥善保管，不要在客户端代码中硬编码

## 许可证

MIT License