finish
This commit is contained in:
jeremygan2021
306
README.md
Normal file
306
README.md
Normal file
@@ -0,0 +1,306 @@
|
||||
# 云南AI共生大会签到系统
|
||||
|
||||
## 项目概述
|
||||
|
||||
这是一个专为云南AI共生大会设计的智能签到系统，基于FastAPI框架开发，提供完整的会议签到解决方案。系统集成了智能座位分配、嘉宾信息管理、同桌推荐等功能，为参会者提供流畅的签到体验。
|
||||
|
||||
## 主要功能
|
||||
|
||||
### 🎯 核心功能
|
||||
- **智能签到流程**：支持手机号或姓名搜索，快速定位参会嘉宾
|
||||
- **智能座位分配**：基于行业分布和人数均衡的算法自动分配座位
|
||||
- **同桌嘉宾推荐**：签到后展示同table的3位随机嘉宾，促进交流
|
||||
- **嘉宾信息补全**：签到时可补充单位、职务、业务范围等信息
|
||||
- **重复签到检测**：自动识别已签到用户，避免重复操作
|
||||
|
||||
### 🔧 管理功能
|
||||
- **新嘉宾添加**：支持现场添加新参会嘉宾
|
||||
- **多用户搜索**：模糊搜索支持，可处理重名情况
|
||||
- **信息验证**：手机号唯一性验证，防止重复注册
|
||||
|
||||
### 🎨 用户体验
|
||||
- **现代化UI设计**：采用AI主题的未来主义风格界面
|
||||
- **响应式布局**：适配各种设备屏幕
|
||||
- **实时反馈**：清晰的操作提示和错误处理
|
||||
- **模态框详情**：点击同桌嘉宾可查看详细信息
|
||||
|
||||
## 技术架构
|
||||
|
||||
### 后端技术栈
|
||||
- **FastAPI**：高性能Python Web框架
|
||||
- **PostgreSQL**：数据持久化存储
|
||||
- **psycopg2**：PostgreSQL数据库适配器
|
||||
- **Pydantic**：数据验证和序列化
|
||||
- **Jinja2**：模板引擎
|
||||
- **UUID**：唯一标识符生成
|
||||
|
||||
### 前端技术
|
||||
- **HTML5 + CSS3**：现代化界面设计
|
||||
- **原生JavaScript**：轻量级交互逻辑
|
||||
- **AJAX**：异步数据交互
|
||||
- **响应式设计**：移动端友好
|
||||
|
||||
### 部署方案
|
||||
- **Docker容器化**：便于部署和扩展
|
||||
- **自动化脚本**：一键构建和部署
|
||||
- **多架构支持**：支持AMD64和ARM64架构
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
.
|
||||
├── main.py # 主应用文件，包含所有API端点
|
||||
├── templates/ # HTML模板目录
|
||||
│ ├── index.html # 主签到页面
|
||||
│ └── add_user.html # 添加新嘉宾页面
|
||||
├── static/ # 静态资源目录
|
||||
│ └── image.jpg # 会议主题图片
|
||||
├── docker_deply.sh # Docker部署自动化脚本
|
||||
├── gsdh.csv # 嘉宾数据文件（示例）
|
||||
└── README.md # 项目文档
|
||||
```
|
||||
|
||||
## 核心算法
|
||||
|
||||
### 座位分配算法
|
||||
系统采用双层策略进行智能座位分配：
|
||||
|
||||
1. **均衡分布**：优先选择人数最少的table，确保13个table人数均衡（每桌最多12人）
|
||||
2. **行业多样性**：在人数最少的table中，选择该行业占比最少的table，促进行业交流
|
||||
|
||||
```python
|
||||
def assign_seat(cur, user_industry: str) -> str:
|
||||
# 1. 统计现有table人数和行业分布
|
||||
# 2. 筛选未满的table（每桌≤12人）
|
||||
# 3. 选择人数最少的table
|
||||
# 4. 在候选table中选择该行业占比最少的
|
||||
# 5. 返回分配的桌号（如"第5桌"）
|
||||
```
|
||||
|
||||
### 同桌推荐算法
|
||||
- 随机选择同table的3位嘉宾（排除自己）
|
||||
- 展示基本信息：姓名、行业、公司、职务、业务范围、2026愿景
|
||||
- 支持点击查看详细信息
|
||||
|
||||
## API接口文档
|
||||
|
||||
### 搜索接口
|
||||
```http
|
||||
GET /api/search?query={phone_or_name}
|
||||
```
|
||||
- 支持手机号精确搜索和姓名模糊搜索
|
||||
- 返回用户信息和签到状态
|
||||
|
||||
### 签到接口
|
||||
```http
|
||||
POST /api/checkin
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"gsdh_id": "uuid",
|
||||
"name": "姓名",
|
||||
"phone": "手机号",
|
||||
"company_name": "公司名称",
|
||||
"position": "职务",
|
||||
"business_scope": "业务范围",
|
||||
"vision_2026": "2026愿景",
|
||||
"location": "座位号"
|
||||
}
|
||||
```
|
||||
|
||||
### 添加用户接口
|
||||
```http
|
||||
POST /api/add-user
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "姓名",
|
||||
"phone": "手机号",
|
||||
"industry_company": "公司/行业"
|
||||
}
|
||||
```
|
||||
|
||||
## 数据库设计
|
||||
|
||||
### 主要数据表
|
||||
|
||||
#### gsdh_data（嘉宾基础信息表）
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| new_id | UUID | 主键，唯一标识 |
|
||||
| name | VARCHAR | 姓名 |
|
||||
| phone | VARCHAR | 手机号（唯一） |
|
||||
| industry_company | VARCHAR | 公司/行业信息 |
|
||||
| is_signed | BOOLEAN | 签到状态 |
|
||||
|
||||
#### checkin_info（签到信息表）
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| id | SERIAL | 主键，自增 |
|
||||
| gsdh_id | UUID | 关联gsdh_data |
|
||||
| name | VARCHAR | 签到时确认的姓名 |
|
||||
| phone | VARCHAR | 签到时确认的手机号 |
|
||||
| company_name | VARCHAR | 公司名称 |
|
||||
| position | VARCHAR | 职务 |
|
||||
| business_scope | TEXT | 业务范围 |
|
||||
| vision_2026 | TEXT | 2026年业务愿景 |
|
||||
| location | VARCHAR | 分配的座位号 |
|
||||
| created_at | TIMESTAMP | 签到时间 |
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
- Python 3.8+
|
||||
- PostgreSQL 12+
|
||||
- Docker（可选）
|
||||
|
||||
### 本地开发
|
||||
|
||||
1. **克隆项目**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd yunnan-ai-conference-checkin
|
||||
```
|
||||
|
||||
2. **安装依赖**
|
||||
```bash
|
||||
pip install fastapi uvicorn psycopg2-binary pydantic jinja2
|
||||
```
|
||||
|
||||
3. **配置数据库**
|
||||
```bash
|
||||
# 创建数据库
|
||||
createdb gsdh
|
||||
|
||||
# 执行SQL初始化脚本（需要创建相关表结构）
|
||||
```
|
||||
|
||||
4. **启动应用**
|
||||
```bash
|
||||
python main.py
|
||||
# 或使用uvicorn
|
||||
uvicorn main:app --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
5. **访问应用**
|
||||
- 主签到页面：http://localhost:8000
|
||||
- 添加嘉宾页面：http://localhost:8000/add-user
|
||||
|
||||
### Docker部署
|
||||
|
||||
1. **构建镜像**
|
||||
```bash
|
||||
# 完整构建和部署流程（默认AMD64架构）
|
||||
./docker_deply.sh
|
||||
|
||||
# 构建ARM64架构镜像
|
||||
./docker_deply.sh -arm
|
||||
|
||||
# 仅上传已存在的tar文件
|
||||
./docker_deply.sh -upload
|
||||
```
|
||||
|
||||
2. **配置参数**
|
||||
编辑 `docker_deply.sh` 脚本顶部的配置：
|
||||
```bash
|
||||
SERVER_HOST="your-server-ip" # 服务器IP地址
|
||||
SERVER_USER="ubuntu" # 服务器用户名
|
||||
SERVER_PASSWORD="your-password" # 服务器密码
|
||||
SERVER_PORT="22" # SSH端口
|
||||
```
|
||||
|
||||
3. **访问应用**
|
||||
部署完成后，通过 `http://your-server-ip:8011` 访问
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 数据库配置
|
||||
在 `main.py` 中修改数据库连接参数：
|
||||
```python
|
||||
DB_CONFIG = {
|
||||
"host": "121.43.104.161",
|
||||
"port": "6432",
|
||||
"user": "gsdh",
|
||||
"password": "123gsdh",
|
||||
"database": "gsdh"
|
||||
}
|
||||
```
|
||||
|
||||
### 座位分配规则
|
||||
- 总table数：13桌
|
||||
- 每桌最大人数：12人
|
||||
- 分配策略：人数均衡 + 行业多样性
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 正常签到流程
|
||||
1. 嘉宾输入手机号或姓名进行搜索
|
||||
2. 系统显示匹配的嘉宾信息
|
||||
3. 嘉宾确认并补充完整信息
|
||||
4. 系统智能分配座位并展示同桌嘉宾
|
||||
5. 签到完成，显示座位号
|
||||
|
||||
### 现场添加嘉宾
|
||||
1. 访问添加嘉宾页面
|
||||
2. 输入新嘉宾的基本信息
|
||||
3. 系统验证手机号唯一性
|
||||
4. 添加成功后，新嘉宾可进行正常签到
|
||||
|
||||
## 安全特性
|
||||
|
||||
- **数据验证**：所有输入都经过Pydantic严格验证
|
||||
- **错误处理**：完善的异常捕获和用户友好的错误提示
|
||||
- **手机号保护**：手机号信息不公开显示
|
||||
- **防重复签到**：基于数据库事务确保数据一致性
|
||||
|
||||
## 性能优化
|
||||
|
||||
- **数据库连接池**：复用数据库连接，减少连接开销
|
||||
- **索引优化**：在搜索字段上建立适当索引
|
||||
- **缓存策略**：静态资源缓存，提升加载速度
|
||||
- **异步处理**：非阻塞的API响应
|
||||
|
||||
## 扩展功能
|
||||
|
||||
### 未来可考虑的功能
|
||||
- **二维码签到**：生成个人二维码，扫码快速签到
|
||||
- **实时统计**：后台实时查看签到进度和统计
|
||||
- **消息推送**：签到成功后发送确认短信/邮件
|
||||
- **数据导出**：支持签到数据导出为Excel等格式
|
||||
- **多语言支持**：支持中英文切换
|
||||
- **人脸识别**：集成人脸识别技术，提升签到体验
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
**Q: 数据库连接失败**
|
||||
A: 检查数据库配置是否正确，确保PostgreSQL服务正常运行
|
||||
|
||||
**Q: 座位分配算法异常**
|
||||
A: 检查数据库中table数据是否完整，确保location字段格式正确
|
||||
|
||||
**Q: 搜索功能无结果**
|
||||
A: 确认数据库中有对应的数据，检查搜索关键词是否正确
|
||||
|
||||
**Q: Docker部署失败**
|
||||
A: 检查服务器配置和网络连接，确保Docker服务正常运行
|
||||
|
||||
## 维护建议
|
||||
|
||||
1. **定期备份**：定期备份数据库，防止数据丢失
|
||||
2. **监控性能**：监控API响应时间和数据库性能
|
||||
3. **日志分析**：定期分析应用日志，发现潜在问题
|
||||
4. **安全更新**：及时更新依赖包，修复安全漏洞
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目采用MIT许可证，详见LICENSE文件。
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有问题或建议，请联系项目维护者。
|
||||
|
||||
---
|
||||
|
||||
**特别说明**：本项目专为云南AI共生大会定制开发，结合了会议的实际需求和AI技术的特色，旨在为参会嘉宾提供便捷、智能的签到体验。
|
||||
Reference in New Issue
Block a user