feishu_screen/Web应用使用说明.md

# Screen2Feishu Web应用使用说明

## 概述

Screen2Feishu Web应用是一个结合了前端界面和后端功能的完整解决方案。它提供了一个用户友好的界面，可以：

1. **手动添加任务**：通过表单添加任务到飞书多维表格
2. **图片上传分析**：上传截图，AI自动分析并生成任务
3. **实时预览**：查看AI分析结果和任务信息
4. **用户匹配**：自动匹配飞书用户，处理重名情况

## 启动应用

### 1. 安装依赖

```bash
pip install flask flask-cors
```

### 2. 配置文件

确保 `config.yaml` 文件已正确配置：

```yaml
ai:
  api_key: "your_api_key"
  base_url: "https://api.openai.com/v1"
  model: "gpt-4o"

feishu:
  app_id: "your_app_id"
  app_secret: "your_app_secret"
  app_token: "your_app_token"
  table_id: "your_table_id"

system:
  watch_folder: "./monitor_images"
  post_process: "keep"
  processed_folder: "./processed_images"
  log_level: "INFO"
  log_file: "app.log"
  memory_processing: false
  
  user_matching:
    enabled: true
    fallback_to_random: true
    cache_enabled: true
    cache_file: "./data/user_cache.json"
```

### 3. 启动应用

```bash
python start_web_app.py
```

或者直接运行：

```bash
python web_app.py
```

### 4. 访问界面

打开浏览器，访问：`http://localhost:5000`

## 功能说明

### 1. 手动添加任务

1. 在"添加新任务..."输入框中输入任务描述
2. 选择截止时间（可选）
3. 选择分类（工作/学习/生活/其他）
4. 选择优先级（高/中/低）
5. 点击"添加"按钮

**AI分析过程**：
- 系统会调用AI服务分析任务描述
- 自动识别任务发起人和部门
- 匹配飞书用户（如果启用）
- 将任务写入飞书多维表格

### 2. 图片上传分析

1. 点击"上传分析"按钮或拖拽图片到文件选择框
2. 选择截图文件（支持JPG、PNG等格式）
3. 系统会自动：
   - 读取图片到内存
   - 调用AI分析图片内容
   - 识别任务信息（描述、优先级、发起人等）
   - 匹配飞书用户
   - 写入飞书表格
   - 在界面显示分析结果

**AI分析结果**：
- 任务描述
- 优先级（紧急/较紧急/一般/普通）
- 状态（未开始/进行中/已完成）
- 发起人姓名
- 部门信息
- 开始日期
- 截止日期

### 3. 任务管理

- **筛选**：按分类、状态、优先级筛选任务
- **编辑**：点击编辑按钮修改任务
- **删除**：点击删除按钮删除任务
- **完成**：勾选复选框标记任务完成

### 4. 通知功能

- **浏览器通知**：启用后可在任务到期时收到通知
- **桌面通知**：显示操作结果和AI分析结果

## API接口

### 1. 上传图片分析

**接口**：`POST /api/upload`

**请求**：
```json
{
  "image": "图片文件"
}
```

**响应**：
```json
{
  "success": true,
  "message": "任务已成功添加到飞书",
  "ai_result": {
    "task_description": "任务描述",
    "priority": "紧急",
    "status": "未开始",
    "initiator": "张三",
    "department": "研发部",
    "start_date": "2026-03-03",
    "due_date": "2026-03-10"
  }
}
```

### 2. 获取用户缓存信息

**接口**：`GET /api/user_cache`

**响应**：
```json
{
  "success": true,
  "stats": {
    "user_count": 10,
    "recent_contact_count": 5,
    "cache_age_hours": 0.5,
    "is_expired": false
  }
}
```

### 3. 获取配置信息

**接口**：`GET /api/config`

**响应**：
```json
{
  "success": true,
  "config": {
    "memory_processing": false,
    "user_matching_enabled": true,
    "fallback_to_random": true,
    "cache_enabled": true,
    "post_process": "keep"
  }
}
```

## 配置说明

### 内存处理模式

```yaml
system:
  memory_processing: true  # 启用内存处理，不保存图片文件
```

### 用户匹配配置

```yaml
system:
  user_matching:
    enabled: true  # 启用用户匹配
    fallback_to_random: true  # 启用随机匹配回退
    cache_enabled: true  # 启用缓存
    cache_file: "./data/user_cache.json"  # 缓存文件路径
```

### 文件处理策略

```yaml
system:
  post_process: "keep"  # 保留原始文件
  # post_process: "delete"  # 删除原始文件
  # post_process: "move"  # 移动到processed_images目录
```

## 使用场景

### 场景1：截图转任务

1. 从聊天记录、邮件或文档中截图
2. 上传截图到Web界面
3. AI自动分析截图内容
4. 生成任务并写入飞书表格

### 场景2：手动创建任务

1. 在Web界面手动输入任务描述
2. AI分析任务内容，提供优化建议
3. 自动匹配任务发起人
4. 写入飞书表格

### 场景3：批量处理

1. 准备多个截图文件
2. 逐个上传分析
3. 系统自动处理并写入飞书

## 注意事项

1. **飞书API权限**：确保飞书应用有读取用户列表和写入表格的权限
2. **图片大小**：建议图片大小不超过10MB
3. **网络连接**：需要稳定的网络连接调用AI和飞书API
4. **浏览器通知**：需要用户授权浏览器通知权限
5. **缓存管理**：用户缓存默认24小时过期，可手动清理

## 故障排除

### 1. 无法启动应用

- 检查依赖是否安装完整
- 检查配置文件是否正确
- 检查端口5000是否被占用

### 2. AI分析失败

- 检查API密钥是否正确
- 检查网络连接
- 查看日志文件 `app.log`

### 3. 飞书写入失败

- 检查飞书API配置
- 检查表格ID和Base Token
- 确保飞书应用有写入权限

### 4. 用户匹配失败

- 检查飞书API权限（用户列表读取）
- 检查缓存文件路径
- 查看日志文件了解详细错误

## 技术架构

### 前端
- HTML5 + CSS3 + JavaScript
- 响应式设计，支持移动端
- 实时通知和状态反馈

### 后端
- Flask Web框架
- AI服务集成（OpenAI格式API）
- 飞书API集成
- 用户缓存管理

### 数据流
1. 用户上传图片/输入任务
2. 前端调用后端API
3. 后端调用AI服务分析
4. 后端匹配飞书用户
5. 后端写入飞书表格
6. 返回结果给前端
7. 前端显示结果和通知

## 扩展功能

### 1. 批量处理
可以扩展支持批量上传和处理多个图片文件

### 2. 实时预览
可以添加图片预览功能，显示上传的截图

### 3. 任务模板
可以添加任务模板功能，快速创建常见任务

### 4. 统计分析
可以添加任务统计和分析功能

### 5. 多语言支持
可以添加多语言界面支持

## 总结

Screen2Feishu Web应用提供了一个完整的解决方案，将前端界面与后端功能完美结合。用户可以通过友好的界面轻松创建任务，AI自动分析并写入飞书表格，大大提高了工作效率。