# 需求分析与设计文档：群聊小朋友照片提取功能

## 1. 需求概述

开发一个基于 deepface 的人脸识别与分析功能，通过权限管理系统控制该功能在群聊中的启用状态。该功能可以自动识别群聊中分享的图片，提取包含小朋友人脸的照片，并按照人脸进行分类整理。

## 2. 功能需求

### 2.1 基本功能
- 通过群权限管理系统控制功能的开启与关闭
- 处理指定目录下的图片文件
- 分析图片中的人脸，识别小朋友的人脸
- 将包含小朋友人脸的图片进行分类存储
- 支持通过指令触发人脸分组功能
- 记录每个群的最后分析时间
- 分析完成后输出详细的分析结果统计

### 2.2 详细需求
1. **权限管理**：
   - 使用现有的 `GroupBotManager` 管理该功能的权限
   - 通过指令启用/关闭该功能

2. **图片处理**：
   - 处理指定目录下的图片文件（不需要处理微信消息）
   - 根据指令处理对应群聊的图片目录
   - 支持常见图片格式（jpg, png, jpeg等）
   - 图片预处理（调整大小、格式转换等）

3. **人脸识别**：
   - 识别图片中的所有人脸
   - 判断人脸是否为小朋友（儿童）
   - 提取小朋友人脸特征用于分组

4. **照片分类**：
   - 为每个识别出的小朋友创建独立文件夹
   - 将包含同一小朋友的照片复制到对应文件夹
   - 处理一张图片中多个小朋友的情况

5. **指令控制**：
   - 提供开始分析的指令
   - 提供查看分析结果的指令
   - 提供清理分析数据的指令
   - 提供查询最后分析时间的指令

6. **分析记录**：
   - 记录每个群的最后分析时间
   - 记录每次分析的统计结果（处理图片数、识别人脸数、分类结果等）
   - 支持查询历史分析记录

7. **结果输出**：
   - 分析完成后自动输出详细的分析结果
   - 包括处理图片总数、识别出的小朋友数量、每个小朋友的照片数量
   - 提供分类后的文件夹路径信息

## 3. 技术方案

### 3.1 技术栈
- **deepface**：用于人脸检测、年龄估计和人脸识别
- **Python**：核心开发语言
- **Redis**：存储权限配置和人脸特征数据
- **OpenCV**：辅助图像处理

### 3.2 系统架构

```
+------------------+     +------------------+     +------------------+
|                  |     |                  |     |                  |
|  权限管理模块     |---->|  图片处理模块     |---->|  人脸识别模块     |
|  (GroupBotManager)|     |  (ImageProcessor) |     |  (FaceAnalyzer)  |
|                  |     |                  |     |                  |
+------------------+     +------------------+     +------------------+
                                                          |
                                                          v
+------------------+     +------------------+     +------------------+
|                  |     |                  |     |                  |
|  指令处理模块     |<----|  照片分类模块     |<----|  人脸分组模块     |
|  (CommandHandler) |     |  (PhotoClassifier)|     |  (FaceGrouper)   |
|                  |     |                  |     |                  |
+------------------+     +------------------+     +------------------+
```

### 3.3 模块设计

#### 3.3.1 权限管理模块
- 使用现有的 `GroupBotManager` 类
- 添加 `KID_PHOTO_EXTRACT` 功能权限（已存在）
- 提供权限检查方法

#### 3.3.2 图片处理模块
- 扫描指定目录下的图片
- 图片预处理（调整大小、格式转换等）
- 支持批量处理多张图片

#### 3.3.3 人脸识别模块
- 使用 deepface 进行人脸检测
- 年龄估计，识别小朋友（例如年龄 < 14 岁）
- 提取人脸特征向量

#### 3.3.4 人脸分组模块
- 基于人脸特征向量进行聚类
- 为每个聚类分配唯一 ID
- 维护人脸 ID 与照片的映射关系

#### 3.3.5 照片分类模块
- 创建分类目录结构
- 将照片复制到对应的分类目录
- 处理一张照片中多个小朋友的情况

#### 3.3.6 指令处理模块
- 解析用户指令
- 触发相应的功能模块
- 返回操作结果消息

## 4. 数据结构设计

### 4.1 Redis 数据结构

1. **权限配置**：
   ```
   group:{group_id}:permissions
   ```
   - 哈希表，存储群组的功能权限配置
   - 包含 KID_PHOTO_EXTRACT 的启用状态

2. **人脸特征数据**：
   ```
   group:{group_id}:kid_faces
   ```
   - 哈希表，存储识别出的小朋友人脸特征
   - 键为人脸 ID，值为特征向量的序列化数据

3. **照片映射**：
   ```
   group:{group_id}:kid_photos:{face_id}
   ```
   - 集合，存储包含特定小朋友的照片路径

4. **分析记录**：
   ```
   group:{group_id}:photo_analysis:last_time
   ```
   - 字符串，存储最后一次分析的时间戳

5. **分析结果**：
   ```
   group:{group_id}:photo_analysis:results
   ```
   - 列表，存储历史分析结果的JSON数据
   - 每次分析后将结果添加到列表头部

### 4.2 文件目录结构

```
/群聊文件目录/
  ├── 原始图片/  # 已下载好的图片目录
  │   ├── image1.jpg
  │   ├── image2.png
  │   └── ...
  └── kid_photos/  # 分析结果目录
      ├── kid_1/
      │   ├── photo1.jpg
      │   └── photo2.jpg
      ├── kid_2/
      │   ├── photo1.jpg
      │   └── photo3.jpg
      └── analysis_report.json  # 分析报告文件
```

## 5. 接口设计

### 5.1 插件接口

```python
class KidPhotoExtractor(PluginInterface):
    def __init__(self, system_context):
        super().__init__("kid_photo_extract", "小朋友照片提取", system_context)
        self.face_analyzer = FaceAnalyzer()
        self.photo_classifier = PhotoClassifier()
        
    def handle_command(self, command, message):
        # 处理用户指令
        pass
        
    def analyze_photos(self, group_id, source_dir):
        # 分析指定目录下的照片
        pass
        
    def generate_report(self, group_id, analysis_result):
        # 生成分析报告
        pass
```

### 5.2 指令接口

1. **开始分析**：
   ```
   #开始分析照片 [可选:目录路径]
   ```
   - 触发对指定目录下图片的分析
   - 如果不指定目录，则使用默认的群聊文件目录

2. **查看结果**：
   ```
   #查看照片分析
   ```
   - 返回最近一次分析结果统计信息

3. **清理数据**：
   ```
   #清理照片分析
   ```
   - 清理分析数据和分类目录

4. **查询分析时间**：
   ```
   #照片分析时间
   ```
   - 返回最后一次分析的时间信息

## 6. 实现流程

### 6.1 权限管理流程

1. 用户发送权限设置指令
2. 系统验证用户权限
3. 更新群组的 KID_PHOTO_EXTRACT 权限状态
4. 返回设置结果

### 6.2 照片分析流程

1. 用户发送开始分析指令（可指定目录）
2. 系统验证群组权限
3. 扫描指定目录中的图片
4. 对每张图片进行人脸检测
5. 识别小朋友人脸并提取特征
6. 对人脸特征进行聚类分组
7. 创建分类目录结构
8. 将照片复制到对应分类目录
9. 生成分析报告并保存
10. 记录分析时间和结果
11. 返回分析完成消息和结果统计

### 6.3 分析结果输出流程

1. 分析完成后自动生成结果报告
2. 报告包含以下内容：
   - 分析时间
   - 处理图片总数
   - 识别出的小朋友总数
   - 每个小朋友的照片数量
   - 分类后的文件夹路径
3. 将报告以文本形式发送到群聊
4. 同时保存报告为JSON文件

## 7. 安全与隐私考虑

1. **数据安全**：
   - 图片处理完成后及时清理临时文件
   - 人脸特征数据加密存储

2. **隐私保护**：
   - 只在功能启用的群组中处理图片
   - 提供清理数据的指令
   - 不上传或分享用户照片到外部服务
   - 分析结果仅在群内可见

3. **权限控制**：
   - 只有群管理员可以启用/关闭该功能
   - 只有授权用户可以触发分析指令

## 8. 性能优化

1. **图片处理优化**：
   - 限制处理图片的大小
   - 使用多线程并行处理多张图片

2. **人脸识别优化**：
   - 缓存已识别的人脸特征
   - 使用轻量级模型进行初步筛选

3. **存储优化**：
   - 定期清理长时间未访问的数据
   - 对大量数据进行分片存储

## 9. 开发计划

### 9.1 阶段一：基础功能实现
- 实现权限管理集成
- 实现基本的人脸检测和年龄估计
- 实现简单的照片分类功能

### 9.2 阶段二：功能完善
- 实现人脸聚类和分组
- 优化小朋友识别准确率
- 完善指令系统

### 9.3 阶段三：性能优化与测试
- 性能优化
- 全面测试
- 文档完善

## 10. 测试计划

### 10.1 单元测试
- 测试人脸检测准确率
- 测试年龄估计准确率
- 测试人脸聚类效果

### 10.2 集成测试
- 测试与权限系统的集成
- 测试与消息系统的集成
- 测试与文件系统的集成

### 10.3 性能测试
- 测试大量图片处理性能
- 测试多人脸图片处理性能
- 测试系统资源占用情况

## 11. 总结

本功能通过 deepface 技术实现群聊中小朋友照片的自动识别与分类，帮助用户更好地管理和整理群聊中分享的照片。该功能与现有的权限管理系统无缝集成，用户可以通过简单的指令控制功能的启用和使用。

实现该功能需要解决人脸检测、年龄估计、人脸聚类等技术挑战，同时需要考虑数据安全和隐私保护问题。通过分阶段开发和全面测试，确保功能的稳定性和可靠性。


接下来的内容：
1.需要支持人脸人工打标，打标之后，记录到数据库里面，作为分析的对比源头。