# tax_ocr_api

**Repository Path**: hugking/tax_ocr_api

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-13
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 验证码匹配 API 服务 (Tax OCR API)

基于 FastAPI 的验证码图片匹配服务，提供HTTP接口进行验证码识别和坐标匹配，支持可视化结果展示。

## 📁 项目结构

```
tax_ocr_api/
├── main.py                    # FastAPI主应用
├── captcha_matcher.py         # 核心匹配模块
├── config.py                  # 配置文件
├── requirements.txt           # Python依赖
├── Dockerfile                 # Docker镜像构建文件
├── docker-compose.yml         # Docker Compose配置
├── test_api.py                # 基础API测试脚本
├── test_visualize.py          # 可视化API测试（base64版）
├── test_visualize_file.py     # 可视化API测试（文件上传版）⭐
├── QUICKSTART.md              # 快速开始指南
└── README.md                  # 本文档
```

## 🚀 快速开始

### 方式1: 本地运行

#### 1. 安装依赖

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

#### 2. 启动服务

```bash
python main.py
```

服务将在 `http://localhost:8000` 启动

#### 3. 访问文档

- **Swagger UI: http://localhost:8000/docs** ⭐ 推荐！可直接看到可视化结果
- ReDoc: http://localhost:8000/redoc
- 健康检查: http://localhost:8000/health

> 💡 **快速体验可视化功能**: 访问 `/docs`，找到 `/visualize` 接口，点击 "Try it out"，图片会直接显示！详见 [QUICKSTART.md](QUICKSTART.md)

### 方式2: Docker部署

#### 1. 构建镜像

```bash
docker build -t captcha-matcher-api .
```

#### 2. 运行容器

```bash
docker run -d -p 8000:8000 --name captcha-api captcha-matcher-api
```

### 方式3: Docker Compose部署（推荐）

```bash
docker-compose up -d
```

查看日志：
```bash
docker-compose logs -f
```

停止服务：
```bash
docker-compose down
```

## 📖 API 接口文档

### 1. 匹配验证码（基础接口）

**接口地址:** `POST /api/v1/captcha/match`

**请求示例:**

```json
{
  "order_img_base64": "iVBORw0KGgoAAAANS...",
  "target_img_base64": "iVBORw0KGgoAAAANS..."
}
```

**响应示例:**

```json
{
  "success": true,
  "code": "0",
  "message": "success",
  "data": {
    "result": "322,100|51,42|180,200|350,150",
    "id": "00504808e68a41ad83ab5c1e6367ae6b"
  }
}
```

**响应字段说明:**

- `success`: 是否成功 (true/false)
- `code`: 状态码
  - `"0"`: 成功
  - `"1000"`: 系统错误
  - `"1001"`: 未找到匹配
  - `"1002"`: 参数错误
- `message`: 消息描述
- `data.result`: 坐标字符串，格式为 `"x1,y1|x2,y2|x3,y3|x4,y4"`
- `data.id`: 唯一请求ID

### 2. 可视化匹配结果（新增）🎨

#### 2.1 文件上传版（推荐，最方便）⭐

**接口地址:** `POST /api/v1/captcha/visualize/file`

**功能说明:** 直接在Swagger UI中上传图片文件，无需转换base64

**使用方式（最简单）:**
1. 访问 http://localhost:8000/docs
2. 找到 `/visualize/file` 接口
3. 点击 "Try it out"
4. 点击 "Choose File" 选择图片：
   - `order_image`: 选择参考图
   - `target_image`: 选择目标图
5. 点击 "Execute"
6. **图片直接显示！** 坐标在响应头中

**Python代码调用:**

```python
import requests

# 直接上传文件
with open("order.png", "rb") as order_f, \
     open("target.png", "rb") as target_f:
    
    files = {
        'order_image': order_f,
        'target_image': target_f
    }
    
    response = requests.post(
        "http://localhost:8000/api/v1/captcha/visualize/file",
        files=files
    )

# 获取坐标
coords = response.headers.get('X-Result-Coordinates')
print(f"坐标: {coords}")

# 保存图片
with open("result.png", "wb") as f:
    f.write(response.content)
```

#### 2.2 Base64版（适合API调用）

**接口地址:** `POST /api/v1/captcha/visualize`

**功能说明:** 接受base64编码的图片，返回标注后的PNG图片

**请求示例:**

```json
{
  "order_img_base64": "iVBORw0KGgoAAAANS...",
  "target_img_base64": "iVBORw0KGgoAAAANS..."
}
```

**响应:**

- **Content-Type**: `image/png`
- **Body**: PNG格式的标注图片（二进制）
- **响应头**:
  - `X-Result-Coordinates`: 坐标字符串，格式为 "x1,y1|x2,y2|x3,y3|x4,y4"
  - `X-Request-ID`: 唯一请求ID
  - `X-Process-Time`: 处理时间（秒）

**使用方式:**
- 🌐 **在 Swagger UI 中**: 访问 http://localhost:8000/docs，点击接口的 "Execute"，图片会直接显示
- 🖼️ **浏览器中**: 直接POST请求，浏览器会显示图片
- 💾 **保存图片**: 响应的body就是PNG图片，直接保存即可
- 📊 **获取坐标**: 从响应头 `X-Result-Coordinates` 获取

**图片标注说明:**
- ✅ 彩色矩形框标识匹配区域
- ✅ 序号标签显示匹配顺序（#1, #2, #3, #4）
- ✅ 白色圆环+实心点标记点击中心
- ✅ 不同颜色区分不同匹配：绿色(#1)、蓝色(#2)、红色(#3)、黄色(#4)
- ✅ **参考图显示在上方右侧**（带白色边框），画布自动向上扩展，不遮挡目标图

### 3. 健康检查

**接口地址:** `GET /health`

**响应示例:**

```json
{
  "status": "healthy",
  "timestamp": "2025-12-13T10:30:00"
}
```

## 🧪 测试

### 测试基础接口

```bash
python test_api.py
```

### 测试可视化接口（推荐）

```bash
python test_visualize.py
```

这会保存标注后的图片到 `visualize_result.png`

### 使用curl测试

**测试基础接口:**
```bash
curl -X POST "http://localhost:8000/api/v1/captcha/match" \
  -H "Content-Type: application/json" \
  -d '{
    "order_img_base64": "your_base64_string",
    "target_img_base64": "your_base64_string"
  }'
```

**测试可视化接口（保存图片）:**
```bash
curl -X POST "http://localhost:8000/api/v1/captcha/visualize" \
  -H "Content-Type: application/json" \
  -d '{
    "order_img_base64": "your_base64_string",
    "target_img_base64": "your_base64_string"
  }' \
  -o result.png -D headers.txt

# 查看坐标（在响应头中）
cat headers.txt | grep X-Result-Coordinates
```

### 使用Python requests

**基础接口（获取坐标）:**
```python
import requests
import base64

# 读取图片
with open("order.png", "rb") as f:
    order_b64 = base64.b64encode(f.read()).decode()

with open("target.png", "rb") as f:
    target_b64 = base64.b64encode(f.read()).decode()

# 发送请求
response = requests.post(
    "http://localhost:8000/api/v1/captcha/match",
    json={
        "order_img_base64": order_b64,
        "target_img_base64": target_b64
    }
)

result = response.json()
print(result)
```

**可视化接口（获取标注图片）:**
```python
import requests
import base64

# 读取图片
with open("order.png", "rb") as f:
    order_b64 = base64.b64encode(f.read()).decode()

with open("target.png", "rb") as f:
    target_b64 = base64.b64encode(f.read()).decode()

# 发送请求
response = requests.post(
    "http://localhost:8000/api/v1/captcha/visualize",
    json={
        "order_img_base64": order_b64,
        "target_img_base64": target_b64
    }
)

# 从响应头获取坐标
coordinates = response.headers.get('X-Result-Coordinates')
print(f"坐标: {coordinates}")

# 保存标注图片
with open("result.png", "wb") as f:
    f.write(response.content)
print("图片已保存到 result.png")
```

## ⚙️ 配置

### 环境变量

可以通过环境变量配置服务：

- `HOST`: 监听地址 (默认: 0.0.0.0)
- `PORT`: 监听端口 (默认: 8000)
- `DEBUG`: 调试模式 (默认: false)
- `LOG_LEVEL`: 日志级别 (默认: INFO)

### 修改配置

编辑 `config.py` 文件进行更详细的配置。

## 📊 性能优化

### 1. 增加Worker数量

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```

### 2. 使用Gunicorn

```bash
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
```

### 3. 使用Nginx反向代理

```nginx
upstream captcha_api {
    server 127.0.0.1:8000;
    server 127.0.0.1:8001;
    server 127.0.0.1:8002;
    server 127.0.0.1:8003;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://captcha_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 🔒 生产环境建议

1. **启用HTTPS**: 使用SSL证书
2. **限制CORS**: 在 `main.py` 中配置具体允许的域名
3. **添加认证**: 实现API密钥或JWT认证
4. **限流**: 添加请求频率限制
5. **监控**: 集成Prometheus/Grafana监控
6. **日志**: 配置结构化日志输出

## 📝 日志

应用日志会输出到控制台，包含以下信息：
- 请求时间和路径
- 处理时长
- 错误堆栈（如有）

## 🐛 故障排查

### 问题1: 端口被占用

```bash
# Windows
netstat -ano | findstr :8000

# Linux
lsof -i :8000
```

### 问题2: AntiCAP模块未安装

确保已正确安装 AntiCAP 包，或将其添加到项目中。

### 问题3: OpenCV错误

```bash
# 安装系统依赖
# Ubuntu/Debian
apt-get install libgl1-mesa-glx libglib2.0-0

# CentOS
yum install mesa-libGL
```

## 📞 技术支持

如遇到问题：
1. 查看日志输出
2. 访问 `/docs` 查看交互式API文档
3. 使用 `test_api.py` 进行本地测试

## 📄 许可证

内部使用项目

## 更新日志

### v1.0.0 (2025-12-13)
- ✅ 初始版本发布
- ✅ 实现基础匹配功能
- ✅ 支持Docker部署
- ✅ 添加健康检查接口