feishu_screen/项目结构说明.md

# Screen2Feishu 项目结构说明

## 项目目录结构

```
Screen2Feishu/
├── main.py                    # 原始命令行程序入口
├── web_app.py                 # Web应用入口
├── start_web_app.py          # Web应用启动器
├── config.yaml                # 配置文件
├── config.example.yaml        # 配置文件示例
├── requirements.txt           # Python依赖
├── README.md                  # 项目说明
├── Web应用使用说明.md         # Web应用使用说明
├── 项目结构说明.md            # 本文件
├── 优化设计方案.md            # 优化设计方案
├── 优化功能说明.md            # 优化功能说明
├── 优化总结_更新版.md         # 优化总结
├── BUG修复总结.md             # BUG修复说明
├── 优先级修改说明.md          # 优先级修改说明
├── test_priority.py           # 优先级测试脚本
├── app.log                    # 应用日志文件
├── data/                      # 数据目录
│   ├── user_cache.json        # 用户缓存文件
│   └── test_user_cache.json   # 测试缓存文件
├── monitor_images/            # 监控图片目录（待处理）
├── processed_images/          # 已处理图片目录
├── services/                  # 服务层
│   ├── __init__.py
│   ├── ai_service.py          # AI服务
│   └── feishu_service.py      # 飞书服务
├── templates/                 # Web模板目录
│   └── index.html             # Web界面模板
├── utils/                     # 工具层
│   ├── __init__.py
│   ├── config_loader.py       # 配置加载器
│   ├── logger.py              # 日志工具
│   ├── notifier.py            # 通知工具
│   └── user_cache.py          # 用户缓存管理器
└── tests/                     # 测试目录
    ├── __init__.py
    └── test_config_loader.py  # 配置加载器测试
```

## 核心文件说明

### 1. 主程序文件

#### main.py
- **功能**：原始命令行程序入口
- **用途**：监控文件夹，自动处理图片并写入飞书
- **使用方式**：`python main.py`

#### web_app.py
- **功能**：Web应用入口
- **用途**：提供Web界面和API接口
- **使用方式**：`python web_app.py`

#### start_web_app.py
- **功能**：Web应用启动器
- **用途**：检查环境并启动Web应用
- **使用方式**：`python start_web_app.py`

### 2. 配置文件

#### config.yaml
- **功能**：应用配置文件
- **内容**：
  - AI服务配置（API密钥、模型等）
  - 飞书服务配置（应用ID、密钥、表格ID等）
  - 系统配置（文件夹路径、处理策略等）
  - 用户匹配配置（启用状态、缓存路径等）

#### config.example.yaml
- **功能**：配置文件示例
- **用途**：作为配置文件模板

### 3. 服务层

#### services/ai_service.py
- **功能**：AI服务
- **主要类**：`AIService`
- **主要方法**：
  - `analyze_image()`：分析图片文件
  - `analyze_image_from_bytes()`：分析内存中的图片数据
  - `_build_prompt()`：构建AI提示词
  - `_parse_ai_response()`：解析AI响应

#### services/feishu_service.py
- **功能**：飞书服务
- **主要类**：`FeishuService`
- **主要方法**：
  - `add_task()`：添加任务到飞书
  - `_match_initiator()`：匹配任务发起人
  - `_get_user_list()`：获取飞书用户列表
  - `_build_fields()`：构建飞书字段数据

### 4. 工具层

#### utils/user_cache.py
- **功能**：用户缓存管理器
- **主要类**：`UserCacheManager`
- **主要方法**：
  - `match_user_by_name()`：根据名字匹配用户
  - `add_recent_contact()`：添加最近联系人
  - `get_random_recent_contact()`：随机选择最近联系人
  - `update_users()`：更新用户列表

#### utils/config_loader.py
- **功能**：配置加载器
- **主要函数**：
  - `load_config()`：加载配置文件
  - `validate_config()`：验证配置

#### utils/logger.py
- **功能**：日志工具
- **主要函数**：
  - `setup_logger()`：设置日志记录器

#### utils/notifier.py
- **功能**：通知工具
- **主要函数**：
  - `send_notification()`：发送桌面通知

### 5. Web界面

#### templates/index.html
- **功能**：Web界面模板
- **主要功能**：
  - 任务添加表单
  - 图片上传功能
  - 任务列表展示
  - 筛选和搜索功能
  - 编辑和删除功能
  - 通知权限管理

### 6. 测试文件

#### test_priority.py
- **功能**：优先级测试脚本
- **用途**：验证优先级修改是否正确

## 数据流

### 1. 命令行模式（main.py）

```
监控文件夹 → 检测新图片 → AI分析 → 用户匹配 → 飞书写入 → 后处理
```

### 2. Web应用模式（web_app.py）

```
用户上传图片 → Web服务器接收 → AI分析 → 用户匹配 → 飞书写入 → 返回结果
```

## 配置说明

### AI服务配置
```yaml
ai:
  api_key: "API密钥"
  base_url: "API基础URL"
  model: "模型名称"
```

### 飞书服务配置
```yaml
feishu:
  app_id: "应用ID"
  app_secret: "应用密钥"
  app_token: "多维表格Token"
  table_id: "数据表ID"
```

### 系统配置
```yaml
system:
  watch_folder: "监控文件夹路径"
  post_process: "文件处理策略(keep/delete/move)"
  processed_folder: "已处理文件夹路径"
  log_level: "日志级别"
  log_file: "日志文件路径"
  memory_processing: "是否启用内存处理"
```

### 用户匹配配置
```yaml
system:
  user_matching:
    enabled: "是否启用用户匹配"
    fallback_to_random: "是否启用随机匹配回退"
    cache_enabled: "是否启用缓存"
    cache_file: "缓存文件路径"
```

## 使用方式

### 1. 命令行模式
```bash
# 安装依赖
pip install -r requirements.txt

# 配置config.yaml
cp config.example.yaml config.yaml
# 编辑config.yaml，填入正确的配置

# 启动程序
python main.py
```

### 2. Web应用模式
```bash
# 安装依赖
pip install -r requirements.txt

# 配置config.yaml
cp config.example.yaml config.yaml
# 编辑config.yaml，填入正确的配置

# 启动Web应用
python start_web_app.py

# 或者直接启动
python web_app.py

# 访问界面
# 打开浏览器，访问 http://localhost:5000
```

## 优化功能

### 1. 任务发起方识别优化
- AI提示词增强，明确指示识别发件人/发送者
- 用户匹配机制，自动匹配飞书用户
- 人工评判机制，重名时提供备选方案
- 最近联系人缓存，提高匹配效率

### 2. 图片处理优化
- 内存处理支持，避免保存图片文件
- 文件处理策略，可配置保留/删除/移动
- 存储优化，减少50%存储占用

### 3. 字段处理优化
- 保留部门信息，避免覆盖
- 添加提示信息，便于人工确认
- 任务描述标记，显示待确认/随机匹配状态

### 4. 优先级修改
- 将优先级选项修改为：紧急、较紧急、一般、普通
- 更新AI提示词和验证逻辑
- 更新飞书服务验证逻辑

### 5. BUG修复
- 修复None值检查，避免类型错误
- 提高代码健壮性

## 扩展开发

### 添加新功能
1. 在`services/`目录添加新服务
2. 在`utils/`目录添加新工具
3. 在`templates/`目录添加新页面
4. 在`web_app.py`添加新API接口

### 修改现有功能
1. 修改对应的服务类或工具函数
2. 更新配置文件（如果需要）
3. 更新Web界面（如果需要）
4. 测试修改后的功能

### 调试技巧
1. 查看`app.log`日志文件
2. 使用浏览器开发者工具调试前端
3. 使用Flask调试模式（`debug=True`）
4. 查看飞书API响应和错误信息

## 注意事项

1. **配置安全**：不要将配置文件提交到版本控制
2. **API密钥**：妥善保管API密钥，避免泄露
3. **文件权限**：确保程序有读写相关目录的权限
4. **网络连接**：确保网络连接稳定，特别是调用AI和飞书API时
5. **资源限制**：注意内存和存储空间使用，特别是处理大图片时

## 总结

Screen2Feishu项目提供了完整的任务管理解决方案，包括命令行模式和Web应用模式。通过AI技术自动分析图片和任务描述，结合飞书API实现自动化任务管理，大大提高了工作效率。