# campus_activity_system

NLP 校园活动信息智能分析处理系统，主要功能包括上传身份证图片、提取姓名和身份证号、活动类型分类和活动信息发布。

## 功能模块

- [x] 学生信息管理
- [x] 身份证 OCR 识别（使用 PaddleOCR）
- [ ] 社团负责人管理
- [ ] 活动信息发布
- [x] 活动类型分类（基于 NLP）

## 技术栈

### 后端
- **框架**: Flask + SQLAlchemy
- **数据库**: MySQL 5.7
- **缓存**: Redis
- **OCR**: PaddleOCR（中文身份证识别）
- **NLP**: Transformers (BERT)

### 核心依赖
- `paddleocr`: 高精度中文 OCR 识别引擎
- `transformers`: 用于活动类型分类的 NLP 模型
- `opencv-python`: 图像处理
- `Flask`: Web 框架
- `SQLAlchemy`: ORM

## 快速开始

### 1. 环境准备

```bash
# 加载环境变量
source /etc/profile

# 确认数据库和 Redis 已启动
# MySQL: localhost:3306 (用户: lyq, 密码: 123456)
# Redis: localhost:6379
```

### 2. 安装依赖

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

### 3. 初始化数据库

```bash
python init_db.py
```

### 4. 启动服务

```bash
python app.py
```

服务将在 `http://localhost:5000` 启动。

## OCR 识别说明

本项目使用 **PaddleOCR** 进行身份证识别，相比 Tesseract 有以下优势：

### 优势
- ✓ 更高的中文识别准确率
- ✓ 无需系统级依赖安装
- ✓ 专门优化的证件识别
- ✓ 自动角度纠正

### 使用方法

```python
from utils.ocr_utils import extract_id_card_info

# 识别身份证
id_info = extract_id_card_info('path/to/id_card.jpg')
print(f"姓名: {id_info['name']}")
print(f"身份证号: {id_info['id_number']}")
```

### 测试 OCR

```bash
# 测试身份证识别
python test_id_card_ocr.py test_images/id_card.jpg

# 测试图像预处理
python utils/image_preprocess.py test_images/id_card.jpg
```

详细的 OCR 配置说明请参考：[docs/PADDLEOCR_SETUP.md](docs/PADDLEOCR_SETUP.md)

## API 接口

### 用户注册（含身份证识别）

```bash
POST /register
Content-Type: multipart/form-data

参数:
- username: 用户名
- email: 邮箱
- image: 身份证图片文件

返回:
{
  "message": "用户注册成功",
  "user": {
    "id": 1,
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "name": "张三",
    "id_number": "110101199001011234"
  }
}
```

### 活动类型分类

```bash
POST /classify
Content-Type: application/json

{
  "description": "人工智能与机器学习讲座"
}

返回:
{
  "activity_type": "学术讲座"
}
```

## 项目结构

```
campus_activity_system/
├── app.py                      # 主应用入口
├── routes.py                   # 路由定义
├── models.py                   # 数据模型
├── utils/
│   ├── ocr_utils.py           # OCR 识别工具（PaddleOCR）
│   ├── nlp_utils.py           # NLP 分类工具
│   └── image_preprocess.py    # 图像预处理工具
├── docs/
│   └── PADDLEOCR_SETUP.md     # PaddleOCR 配置文档
├── test_id_card_ocr.py        # OCR 测试脚本
├── requirements.txt            # Python 依赖
├── CLAUDE.md                   # 项目规范
└── README.md                   # 本文档
```

## 模型缓存

### Transformers 模型
```
~/.cache/huggingface/hub/models--dslim--bert-base-NER
```

### PaddleOCR 模型
首次运行会自动下载模型文件（约 50MB）

## 数据库配置

```python
# MySQL 配置
SQLALCHEMY_DATABASE_URI = 'mysql+pymysql://lyq:123456@localhost:3306/campus_activity'

# Redis 配置
REDIS_HOST = 'localhost'
REDIS_PORT = 6379
```

## 常见问题

### Q: OCR 识别准确率不高？
**A**: 请确保：
1. 图片清晰，文字可辨识
2. 光线均匀，避免反光
3. 尽量正面拍摄
4. 建议宽度 1000-2000px

可以使用图像预处理工具提高识别率：
```bash
python utils/image_preprocess.py your_id_card.jpg
```

### Q: 如何启用 GPU 加速？
**A**: 
```bash
pip uninstall paddlepaddle
pip install paddlepaddle-gpu
```

然后在 `utils/ocr_utils.py` 中修改：
```python
ocr = PaddleOCR(use_angle_cls=True, lang='ch', use_gpu=True)
```

### Q: 模型下载慢？
**A**: 首次运行会自动下载模型，如下载慢可使用国内镜像或手动下载。

## 开发指南

详细的开发规范和技术选型请参考：[CLAUDE.md](CLAUDE.md)

## 参考资料

- [PaddleOCR 官方文档](https://github.com/PaddlePaddle/PaddleOCR)
- [Hugging Face - dslim/bert-base-NER](https://huggingface.co/dslim/bert-base-NER)
- [Flask 文档](https://flask.palletsprojects.com/)
- [SQLAlchemy 文档](https://www.sqlalchemy.org/)

## License

[Apache License 2.0](LICENSE)