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服务配置

ai:
  api_key: "API密钥"
  base_url: "API基础URL"
  model: "模型名称"

飞书服务配置

feishu:
  app_id: "应用ID"
  app_secret: "应用密钥"
  app_token: "多维表格Token"
  table_id: "数据表ID"

系统配置

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

用户匹配配置

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

使用方式

1. 命令行模式

# 安装依赖
pip install -r requirements.txt

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

# 启动程序
python main.py

2. Web应用模式

# 安装依赖
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实现自动化任务管理，大大提高了工作效率。