# 审批流程更新说明

**更新时间**: 2026-04-18
**版本**: v2.0

## 变更概述

将审批消息发送从"单一审批群"改为"个人 + 项目群"双通道模式。

## 修改内容

### 1. 消息发送目标调整

| 配置项 | 之前 | 现在 | 说明 |
|--------|------|------|------|
| 个人私聊 | ❌ 不发送 | ✅ 发送 | ou_498988d823b61ab89c9afe4310f85bb4 |
| 项目群聊 | ⚠️ 仅通知（简化消息）| ✅ 完整审批消息 | oc_7940ec97cde40b245cff9cb606ff1ac7 |
| 审批群聊 | ✅ 发送 | ❌ 停用 | oc_88e0a1970a7de02eb5ac225a8b0cedea |

### 2. 审批回复监听

**之前**：
- 只监听审批群（oc_88e0a1970a7de02eb5ac225a8b0cedea）
- 只接受特定用户（ou_498988d823b61ab89c9afe4310f85bb4）的回复

**现在**：
- 监听个人私聊（ou_498988d823b61ab89c9afe4310f85bb4）
- 监听项目群聊（oc_7940ec97cde40b245cff9cb606ff1ac7）
- 接受**任何用户**的回复（不限制个人ID）

### 3. 代码修改位置

**文件**: `tools/im_approval.py`

**修改行数**:
- 第457-470行：消息发送逻辑
- 第476-525行：在线表格/文件发送逻辑
- 第576-584行：审批回复监听（阻塞模式）
- 第714-722行：审批回复监听（check_approval_status）

### 4. 配置文件

**`.env`** 配置：
```bash
# 个人 Open ID（接收审批消息）
FEISHU_OPERATOR_OPEN_ID=ou_498988d823b61ab89c9afe4310f85bb4

# 项目群聊 ID（接收审批消息）
FEISHU_AD_PROJECT_CHAT_ID=oc_7940ec97cde40b245cff9cb606ff1ac7

# 旧审批群聊 ID（已停用，保留兼容）
FEISHU_OPERATOR_CHAT_ID=oc_88e0a1970a7de02eb5ac225a8b0cedea
```

## 端到端测试

### 测试脚本
```bash
cd examples/auto_put_ad_mini
python3 test_approval_flow_e2e.py
```

### 测试结果
```
✅ 个人消息发送成功（message_id: om_x100b5117fbbc44a0c4abd3016f812f0）
✅ 项目群消息发送成功（message_id: om_x100b5117fbb534b0c3705152a30b4f1）
```

### 验证步骤
1. ✅ 检查个人飞书消息，确认收到完整审批消息
2. ✅ 检查项目群聊，确认收到相同的审批消息
3. ✅ 在任一位置回复"通过"或"拒绝"，系统能正确识别

## 使用指南

### 审批流程

1. **系统发起审批**：调用 `send_approval_request` 工具
2. **消息发送**：
   - 个人私聊收到文本消息 + Excel表格
   - 项目群聊收到文本消息 + Excel表格
3. **运营回复**：
   - 在个人私聊中回复"通过"/"拒绝"
   - 或在项目群中回复"通过"/"拒绝"
   - 系统识别任一处的回复
4. **系统执行**：根据回复执行相应操作

### 回复示例

**简单审批**：
- ✅ "通过" → 批准所有操作
- ❌ "拒绝" → 拒绝所有操作

**部分审批**：
- "只批准降价的" → 过滤后执行
- "广告12345不要暂停" → 修改决策后重新审批

### 权限说明

**个人私聊**：
- 仅指定个人（ou_498988d823b61ab89c9afe4310f85bb4）能看到
- 任何人回复都能识别（如果转发给他人）

**项目群聊**：
- 群内所有成员都能看到消息
- **任何群成员**都可以回复审批

## 注意事项

1. **机器人权限**：
   - 确保机器人已加入项目群聊
   - 确保机器人有发送消息和文件权限
   - 确保机器人有读取消息权限

2. **个人私聊**：
   - 用户需要先与机器人建立会话
   - 可以通过在任意群聊@机器人来激活

3. **回复识别**：
   - 系统会监听**审批消息发送后**的所有回复
   - 只识别**用户类型**的消息（忽略机器人消息）
   - 回复内容通过 `_parse_approval_reply` 解析

## 回滚方案

如果需要回滚到旧版（仅审批群）：

1. 修改 `im_approval.py` 第457-470行：
```python
# 恢复为只发送到审批群
result = _feishu.send_message(to=FEISHU_OPERATOR_CHAT_ID, text=message)
```

2. 修改监听逻辑（第576-584行）：
```python
# 恢复为只监听审批群
result = _feishu.get_message_list(
    chat_id=FEISHU_OPERATOR_CHAT_ID,
    start_time=sent_time_sec,
    page_size=10,
)
```

3. 恢复个人ID限制（第593行）：
```python
# 恢复为只接受特定用户
if sender_type != "user" or sender_id != FEISHU_OPERATOR_OPEN_ID:
    continue
```

## 相关文件

- `tools/im_approval.py` - 核心审批逻辑
- `config.py` - 配置定义
- `.env` - 环境变量配置
- `test_approval_flow_e2e.py` - 端到端测试脚本

## 更新日志

### v2.0 (2026-04-18)
- ✅ 支持个人 + 项目群双通道发送
- ✅ 移除审批群聊发送
- ✅ 允许任何群成员回复审批
- ✅ 添加端到端测试脚本

### v1.0 (之前)
- 单一审批群聊模式
- 仅指定用户可回复