# visa_tracker_api

**Repository Path**: XWORK/visa_tracker_api

## Basic Information

- **Project Name**: visa_tracker_api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-30
- **Last Updated**: 2025-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Visa Tracker API

基于 FastAPI 的签证追踪 API 项目，集成了 pydiscourse、requests 和网页解析功能，使用 MongoDB 作为数据库。

## 环境要求

- Python 3.10
- MongoDB 5.0+
- Conda (推荐) 或 pip

## MongoDB 安装和配置

### Windows MongoDB 安装

1. **下载 MongoDB Community Server**：
   ```powershell
   # 使用 Chocolatey 安装（推荐）
   choco install mongodb
   
   # 或从官网下载安装包
   # https://www.mongodb.com/try/download/community
   ```

2. **启动 MongoDB 服务**：
   ```powershell
   # 启动 MongoDB 服务
   net start MongoDB
   
   # 或手动启动
   mongod --dbpath C:\data\db
   ```

3. **验证安装**：
   ```powershell
   # 连接到 MongoDB
   mongosh
   ```

### 数据库配置

在项目根目录创建 `.env` 文件（参考 `.env.example`）：

```env
# MongoDB 配置 - 方式1：分别设置
MONGODB_URL=mongodb://localhost:27017
MONGODB_DATABASE=visa_tracker
MONGODB_USERNAME=admin
MONGODB_PASSWORD=password123

# MongoDB 配置 - 方式2：完整连接字符串（二选一）
# MONGODB_URL=mongodb://admin:password123@localhost:27017
# MONGODB_DATABASE=visa_tracker
```

## 环境安装

### 方法一：使用清华镜像源手动创建环境（推荐）

#### 1. 配置清华镜像源

```powershell
# 配置 conda 清华镜像源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
conda config --set show_channel_urls yes

# 配置 pip 清华镜像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
```

#### 2. 创建 conda 环境脚本

创建 `create_env_manual.bat` 文件：

```batch
@echo off
chcp 65001 >nul
echo.
echo ===== 创建 Visa Tracker API 环境 =====
echo.

:: 删除已存在的环境
echo 删除旧环境（如果存在）...
conda env remove -n visa_tracker_api -y >nul 2>&1

:: 创建新的 Python 3.10 环境
echo 创建 Python 3.10 环境...
conda create -n visa_tracker_api python=3.10 -y

:: 激活环境
echo 激活环境...
call conda activate visa_tracker_api

:: 升级 pip
echo 升级 pip...
python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple

:: 安装依赖包
echo 安装 FastAPI 相关依赖...
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
 

echo.
echo 环境创建完成！
echo.
echo 要激活环境，请运行：
echo conda activate visa_tracker_api
echo.
pause
```

#### 3. 运行脚本创建环境

```powershell
# 运行镜像源配置脚本（如果有）
.\setup_mirrors.bat

# 运行环境创建脚本
.\create_env_manual.bat

# 或者手动执行以下命令：
conda create -n visa_tracker_api python=3.10 -y
conda activate visa_tracker_api
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 方法二：使用 environment.yml 创建环境

```powershell
# 创建 conda 环境
conda env create -f environment.yml

# 激活环境
conda activate visa_tracker_api

# 验证安装
python --version
python -c "import fastapi; print('FastAPI version:', fastapi.__version__)"
```

### 方法二：使用 pip 安装

```powershell
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境 (Windows PowerShell)
.\venv\Scripts\Activate.ps1

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

### 环境管理脚本

#### 创建环境脚本 (create_env.ps1)

```powershell
# 检查是否安装了 conda
if (!(Get-Command conda -ErrorAction SilentlyContinue)) {
    Write-Host "错误: 未找到 conda 命令。请先安装 Anaconda 或 Miniconda。" -ForegroundColor Red
    exit 1
}

Write-Host "正在创建 conda 环境..." -ForegroundColor Green

# 删除已存在的环境（如果有）
conda env remove -n visa_tracker_api -y 2>$null

# 创建新环境
conda env create -f environment.yml

if ($LASTEXITCODE -eq 0) {
    Write-Host "环境创建成功！" -ForegroundColor Green
    Write-Host "请运行以下命令激活环境:" -ForegroundColor Yellow
    Write-Host "conda activate visa_tracker_api" -ForegroundColor Cyan
} else {
    Write-Host "环境创建失败！" -ForegroundColor Red
    exit 1
}
```

#### 激活环境脚本 (activate_env.ps1)

```powershell
# 激活 conda 环境
conda activate visa_tracker_api

if ($LASTEXITCODE -eq 0) {
    Write-Host "环境已激活！" -ForegroundColor Green
    Write-Host "当前 Python 版本:" -ForegroundColor Yellow
    python --version
    Write-Host "FastAPI 版本:" -ForegroundColor Yellow
    python -c "import fastapi; print(fastapi.__version__)"
} else {
    Write-Host "环境激活失败！请检查环境是否已创建。" -ForegroundColor Red
}
```

## 项目结构

```
visa_tracker_api/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 应用入口
│   ├── config.py            # 配置文件
│   ├── models/              # 数据模型
│   ├── routers/             # API 路由
│   ├── services/            # 业务逻辑
│   │   ├── discourse.py     # Discourse API 服务
│   │   └── scraper.py       # 网页爬取服务
│   └── utils/               # 工具函数
├── tests/                   # 测试文件
├── requirements.txt         # pip 依赖文件
├── environment.yml          # conda 环境文件
├── .env                     # 环境变量
├── .gitignore              # Git 忽略文件
└── README.md               # 项目说明
```

## 主要依赖说明

### FastAPI 相关
- `fastapi`: 现代、快速的 Web 框架
- `uvicorn`: ASGI 服务器
- `pydantic`: 数据验证和设置管理

### HTTP 请求
- `requests`: 简单的 HTTP 库
- `httpx`: 支持异步的 HTTP 客户端
- `pydiscourse`: Discourse 论坛 API 客户端

### 网页解析
- `beautifulsoup4`: HTML/XML 解析器
- `lxml`: 高性能 XML 和 HTML 解析器
- `html5lib`: 纯 Python HTML5 解析器
- `selenium`: Web 浏览器自动化
- `scrapy`: 爬虫框架

### 数据库支持 - MongoDB

- `pymongo`: Python MongoDB 驱动
- `motor`: 异步 MongoDB 驱动  
- `beanie`: MongoDB ODM (Object Document Mapper)

## 快速开始

### 一键管理脚本

我们提供了一个综合的项目管理脚本，包含所有常用操作：

```powershell
# 运行项目管理脚本
.\project_manager.bat
```

该脚本提供以下功能：
1. 配置清华镜像源
2. 创建环境（使用批处理脚本）
3. 创建环境（使用 environment.yml）
4. 激活环境并启动项目
5. 仅激活环境
6. 初始化数据库
7. 运行依赖测试

### 简化版安装步骤

1. **配置清华镜像源（可选但推荐）**：
   ```powershell
   .\setup_mirrors.bat
   ```

2. **创建环境（三种方式任选其一）**：
   ```powershell
   # 方式1: 使用批处理脚本（推荐）
   .\create_env_manual.bat
   
   # 方式2: 使用 PowerShell 脚本
   .\create_env_manual.ps1
   
   # 方式3: 使用 environment.yml
   conda env create -f environment.yml
   ```

3. **激活环境并启动项目**：
   ```powershell
   conda activate visa_tracker_api
   
   # 初始化数据库（可选）
   python init_database.py
   
   # 启动开发服务器（推荐方式）
   python run_server.py
   
   # 或使用 uvicorn 命令
   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   ```

### VS Code 开发和调试

项目已经配置了完整的 VS Code 开发环境：

**调试配置**：
- `FastAPI 服务器 (推荐)` - 使用 uvicorn 模块启动，支持热重载和调试
- `调试 main.py 文件` - 直接调试 main.py 文件
- `测试 MongoDB 连接` - 调试数据库连接
- `初始化数据库` - 调试数据库初始化脚本

**使用方法**：
1. 在 VS Code 中打开项目
2. 按 `F5` 或点击"运行和调试"
3. 选择"FastAPI 服务器 (推荐)"
4. 服务器将在调试模式下启动，支持断点调试

**任务配置**：
- 按 `Ctrl+Shift+P` → "Tasks: Run Task"
- 选择相应任务：启动服务器、运行测试、代码格式化等

4. **访问 API 文档**：
   - Swagger UI: <http://localhost:8000/docs>
   - ReDoc: <http://localhost:8000/redoc>
   - 数据库统计: <http://localhost:8000/database/stats>

### 📚 API 端点说明

#### 签证管理 API (`/visa/`)
- `GET /visa/applications` - 获取签证申请列表
- `POST /visa/applications` - 创建新申请
- `GET /visa/applications/{id}` - 获取特定申请详情
- `PUT /visa/applications/{id}` - 更新申请信息
- `DELETE /visa/applications/{id}` - 删除申请
- `GET /visa/statistics` - 获取统计信息
- `GET /visa/search` - 搜索申请

#### Discourse API (`/discourse/`)
- `GET /discourse/posts/latest` - 获取最新帖子
- `GET /discourse/posts/search?q=keyword` - 搜索帖子
- `GET /discourse/posts/by-tags?tags=visa&tags=travel` - 通过标签搜索帖子
- `GET /discourse/posts/with-any-tags?tags=visa&tags=travel` - OR 查询（包含任意标签）
- `GET /discourse/posts/with-all-tags?tags=visa&tags=travel` - AND 查询（包含所有标签）
- `GET /discourse/categories/{id}/topics` - 获取分类下的主题
- `GET /discourse/topics/{id}/posts` - 获取主题下的帖子
- `POST /discourse/posts` - 创建新帖子

#### 系统 API
- `GET /` - API 信息
- `GET /health` - 健康检查
- `GET /database/stats` - 数据库统计

### 详细安装步骤

1. 克隆项目并进入目录
2. 创建并激活环境
3. 运行开发服务器：

```powershell
# 激活环境
conda activate visa_tracker_api

# 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

4. 访问 API 文档：http://localhost:8000/docs

## 开发工具

- 代码格式化：`black .`
- 代码检查：`flake8 .`
- 类型检查：`mypy .`
- 运行测试：`pytest`

## 环境变量

在项目根目录创建 `.env` 文件：

```env
# API 配置
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=True

# Discourse 配置
DISCOURSE_BASE_URL=https://your-discourse-site.com
DISCOURSE_API_KEY=your_api_key
DISCOURSE_USERNAME=your_username

# MongoDB 配置
MONGODB_URL=mongodb://localhost:27017
MONGODB_DATABASE=visa_tracker

# Redis 配置（可选）
REDIS_URL=redis://localhost:6379
```

## 注意事项

1. 确保已安装 Anaconda 或 Miniconda
2. 如使用 Selenium，需要下载对应的浏览器驱动
3. 开发时建议使用虚拟环境
4. 生产环境建议使用 Docker 部署