Face_reg_app/FaceFeatureExtractorAPI/USER_GUIDE.md

# 人脸识别管理系统使用指南

## 🎯 系统简介

这是一个完整的人脸识别管理系统,支持:
- ✅ **Web后台注册**: 通过Web管理后台注册用户
- ✅ **后端存储**: SQLite数据库集中存储用户特征
- ✅ **Android识别**: Android设备直接调用后端识别API
- ✅ **统一管理**: 所有设备共享同一个用户库

---

## 📦 系统架构

```
┌─────────────────────────┐
│   Web管理后台           │
│   http://IP:8000/admin  │
│   - 注册用户            │
│   - 查看用户列表        │
│   - 删除用户            │
│   - 查看统计            │
└───────────┬─────────────┘
            │
            ↓
┌─────────────────────────┐
│   FastAPI后端服务       │
│   - 用户管理API         │
│   - 人脸识别API         │
│   - SQLite数据库        │
│   - 特征提取引擎        │
└───────────┬─────────────┘
            │
            ↓
    ┌───────┴────────┐
    ↓                ↓
┌─────────┐    ┌─────────┐
│Android1 │    │Android2 │
│ 识别    │    │ 识别    │
└─────────┘    └─────────┘
```

---

## 🚀 快速开始

### 步骤1: 安装后端依赖

```bash
cd E:\face\FaceFeatureExtractorAPI
pip install -r requirements.txt
```

### 步骤2: 启动后端服务

```bash
python app.py
```

**预期输出**:
```
🚀 启动服务: http://0.0.0.0:8000
📚 API文档: http://0.0.0.0:8000/docs
🎛️ 管理后台: http://0.0.0.0:8000/admin
INFO:     Uvicorn running on http://0.0.0.0:8000
✅ 数据库初始化完成
```

### 步骤3: 打开Web管理后台

在浏览器中访问: `http://192.168.0.148:8000/admin`

你会看到一个美观的管理界面:
- 统计面板(用户数、识别次数等)
- 用户注册表单
- 用户列表

### 步骤4: 注册用户

在Web管理后台:
1. 输入姓名(必填)
2. 输入年龄(可选)
3. 上传人脸照片
4. 点击"注册用户"

**提示**:
- 照片必须包含清晰的人脸
- 支持jpg/png格式
- 建议正面照,光线充足

### 步骤5: Android端识别

Android应用**无需修改**,保持原有功能:
- 活体检测在本地完成
- 识别时调用后端 `/api/recognize` 接口
- 后端在数据库中查找匹配用户
- 返回识别结果

---

## 🔧 API接口文档

### 1. 用户注册

**POST** `/api/users/register`

**请求(multipart/form-data)**:
```
name: 张三 (必填)
age: 25 (可选)
image: [人脸照片文件] (必填)
```

**响应**:
```json
{
  "success": true,
  "message": "用户 '张三' 注册成功",
  "user_id": 1,
  "user": {
    "id": 1,
    "name": "张三",
    "age": 25,
    "feature_dim": 1024,
    "photo_filename": "张三_20251020_143022.jpg",
    "created_at": "2025-10-20T14:30:22",
    "is_active": true
  }
}
```

---

### 2. 获取用户列表

**GET** `/api/users/list?skip=0&limit=100&active_only=true`

**响应**:
```json
{
  "success": true,
  "message": "查询成功",
  "total": 10,
  "users": [
    {
      "id": 1,
      "name": "张三",
      "age": 25,
      "feature_dim": 1024,
      "photo_filename": "张三_20251020_143022.jpg",
      "created_at": "2025-10-20T14:30:22",
      "is_active": true
    }
  ]
}
```

---

### 3. 人脸识别 (核心接口)

**POST** `/api/recognize`

**请求(multipart/form-data)**:
```
image: [待识别的人脸照片] (必填)
device_id: android_001 (可选)
threshold: 0.7 (可选,默认0.7)
```

**响应(识别成功)**:
```json
{
  "success": true,
  "message": "识别成功: 张三",
  "recognized": true,
  "user_id": 1,
  "user_name": "张三",
  "similarity": 0.8543,
  "threshold": 0.7,
  "processing_time": 0.52
}
```

**响应(未识别)**:
```json
{
  "success": true,
  "message": "未识别到注册用户 (最高相似度: 0.62)",
  "recognized": false,
  "similarity": 0.62,
  "threshold": 0.7,
  "processing_time": 0.48
}
```

---

### 4. 同步用户数据

**GET** `/api/users/sync`

返回所有用户的完整数据(包含特征向量),供Android端下载到本地

**响应**:
```json
{
  "success": true,
  "message": "同步成功",
  "total": 10,
  "users": [
    {
      "id": 1,
      "name": "张三",
      "age": 25,
      "feature_dim": 1024,
      "feature": [0.123, 0.456, ..., 0.789],  // 1024维特征向量
      "photo_filename": "张三_20251020_143022.jpg",
      "created_at": "2025-10-20T14:30:22",
      "is_active": true
    }
  ]
}
```

---

### 5. 删除用户

**DELETE** `/api/users/{user_id}`

**响应**:
```json
{
  "success": true,
  "message": "用户 '张三' 已删除"
}
```

注意:这是软删除,用户数据仍保留在数据库中,但`is_active`设置为false

---

### 6. 统计信息

**GET** `/api/stats`

**响应**:
```json
{
  "success": true,
  "stats": {
    "total_users": 10,
    "total_recognitions": 100,
    "successful_recognitions": 85,
    "recognition_rate": 85.0
  }
}
```

---

## 📱 Android端修改(可选)

目前Android端已经兼容后端识别,无需修改。如果需要从Android端注册用户到后端,可以添加以下功能:

### 选项1: 保持当前模式(推荐)

- **Web后台注册** → 后端数据库
- **Android识别** → 调用后端 `/api/recognize`

### 选项2: Android也支持注册到后端

修改RegisterActivity.java,在注册成功后调用后端注册API:

```java
// 在extractAndRegister方法的onSuccess中添加
NetworkManager.getInstance().registerUserToBackend(
    bitmap,
    name,
    1,  // age
    new NetworkManager.ApiCallback<>() {
        @Override
        public void onSuccess(RegisterResponse result) {
            Toast.makeText(RegisterActivity.this,
                "用户已同步到后端", Toast.LENGTH_SHORT).show();
        }

        @Override
        public void onFailure(String error) {
            Log.w(TAG, "后端同步失败: " + error);
        }
    }
);
```

---

## 🗂️ 数据库结构

### users表
```sql
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(100) NOT NULL UNIQUE,  -- 姓名
    age INTEGER,                         -- 年龄
    feature_vector BLOB NOT NULL,        -- 1024维特征(二进制)
    feature_dim INTEGER DEFAULT 1024,    -- 特征维度
    photo_filename VARCHAR(255),         -- 照片文件名
    created_at TIMESTAMP,                -- 创建时间
    updated_at TIMESTAMP,                -- 更新时间
    is_active BOOLEAN DEFAULT TRUE       -- 是否激活
);
```

### recognition_logs表
```sql
CREATE TABLE recognition_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER,                  -- 识别到的用户ID
    user_name VARCHAR(100),           -- 识别到的用户姓名
    device_id VARCHAR(100),           -- 设备ID
    similarity FLOAT,                 -- 相似度
    threshold FLOAT DEFAULT 0.7,      -- 阈值
    is_recognized BOOLEAN DEFAULT FALSE,  -- 是否识别成功
    recognized_at TIMESTAMP,          -- 识别时间
    photo_filename VARCHAR(255)       -- 识别时的照片
);
```

---

## 📂 目录结构

```
FaceFeatureExtractorAPI/
├── app.py                          # 主应用(V2.0)
├── database.py                     # 数据库模型
├── face_feature_extractor.py      # 特征提取器
├── admin.html                      # Web管理后台
├── requirements.txt                # Python依赖
├── face_recognition.db             # SQLite数据库(自动生成)
└── uploads/                        # 上传文件目录(自动生成)
    ├── photos/                     # 用户照片
    └── logs/                       # 识别记录照片
```

---

## 🧪 测试流程

### 1. 测试后端健康检查
```bash
curl http://192.168.0.148:8000/health
```

预期:
```json
{
  "status": "healthy",
  "extractor_loaded": true,
  "database_connected": true,
  "total_users": 0
}
```

### 2. 测试Web注册
1. 打开 `http://192.168.0.148:8000/admin`
2. 填写姓名"测试用户"
3. 上传一张人脸照片
4. 点击"注册用户"
5. 查看用户列表是否显示新用户

### 3. 测试API注册(使用Postman或curl)
```bash
curl -X POST http://192.168.0.148:8000/api/users/register \
  -F "name=测试用户" \
  -F "age=25" \
  -F "image=@/path/to/face.jpg"
```

### 4. 测试识别API
```bash
curl -X POST http://192.168.0.148:8000/api/recognize \
  -F "image=@/path/to/face.jpg" \
  -F "device_id=test_device" \
  -F "threshold=0.7"
```

### 5. 测试Android端
1. 确保Android设备和电脑在同一WiFi
2. 打开Android应用
3. 点击"人脸识别"
4. 对准摄像头
5. 活体检测通过后自动识别
6. 查看是否显示注册的用户姓名

---

## ⚙️ 配置选项

### 修改识别阈值

在 `app.py` 中搜索 `threshold`,修改默认值:
```python
threshold: float = Form(0.7, description="识别阈值"),
```

或者在调用 `/api/recognize` 时传递自定义阈值:
```
threshold=0.75
```

### 修改数据库路径

在 `database.py` 中修改:
```python
DATABASE_URL = "sqlite:///./face_recognition.db"
```

### 修改照片存储路径

在 `app.py` 中修改:
```python
UPLOAD_DIR = Path("uploads")
PHOTOS_DIR = UPLOAD_DIR / "photos"
```

---

## 🔒 生产环境建议

1. **使用HTTPS**: 配置SSL证书,保护数据传输
2. **使用PostgreSQL**: 替换SQLite,提高并发性能
3. **添加身份验证**: API添加Token验证
4. **数据备份**: 定期备份数据库和照片
5. **日志监控**: 记录所有API请求和识别记录
6. **限流保护**: 防止恶意请求

---

## 🐛 故障排除

### 问题1: 数据库初始化失败

**现象**: 启动时报错 `ImportError: cannot import name 'User' from 'database'`

**解决**:
```bash
# 确保database.py存在且无语法错误
python -c "from database import User, init_database; init_database()"
```

### 问题2: 识别总是失败

**检查**:
1. 后端是否有注册用户: 访问 `/api/users/list`
2. 识别阈值是否过高: 尝试降低到 0.6
3. 照片质量是否合格: 确保光线充足,人脸清晰

### 问题3: Android无法连接后端

**检查**:
1. 电脑防火墙是否开放8000端口
2. Android和电脑是否在同一WiFi
3. IP地址是否正确配置
4. Web API是否正在运行

---

## 📊 性能优化

### 数据库优化
```sql
-- 为常用查询添加索引
CREATE INDEX idx_users_name ON users(name);
CREATE INDEX idx_users_active ON users(is_active);
CREATE INDEX idx_logs_recognized_at ON recognition_logs(recognized_at);
```

### 特征向量缓存
```python
# 在app.py中添加缓存(可选)
from functools import lru_cache

@lru_cache(maxsize=100)
def get_user_features_cached(user_id):
    # 缓存用户特征向量
    pass
```

---

## 📝 更新日志

### V2.0.0 (2025-10-20)
- ✅ 添加SQLite数据库支持
- ✅ 实现用户注册API
- ✅ 实现后端识别API
- ✅ 创建Web管理后台
- ✅ 添加识别日志记录
- ✅ 支持统计功能
- ✅ 支持用户同步

### V1.0.0
- ✅ 基础特征提取API
- ✅ 特征对比API
- ✅ 无状态服务

---

## 🆘 获取帮助

如果遇到问题:
1. 查看后端日志: 终端输出
2. 查看API文档: `http://192.168.0.148:8000/docs`
3. 检查数据库: 使用SQLite浏览器打开 `face_recognition.db`
4. 查看识别记录: 查询 `recognition_logs` 表

---

## 🎉 快速测试命令

```bash
# 1. 安装依赖
cd E:\face\FaceFeatureExtractorAPI
pip install -r requirements.txt

# 2. 启动服务
python app.py

# 3. 在浏览器打开管理后台
start http://192.168.0.148:8000/admin

# 4. 测试健康检查
curl http://192.168.0.148:8000/health

# 5. 查看用户列表
curl http://192.168.0.148:8000/api/users/list

# 6. 查看统计
curl http://192.168.0.148:8000/api/stats
```

**现在可以开始使用了!** 🚀