x-server-mobile/docs/DEPLOYMENT_STEPS.md

# 线上部署和调试步骤

**版本**: 1.0.0
**更新时间**: 2026-02-28
**分支**: feature/debug-feishu-message

---

## 📋 部署前检查清单

### 代码变更文件
```
backend/app/model/FeishuMessage.php           # 新建 - 消息映射模型
backend/app/model/FeishuMessageLog.php        # 新建 - 消息日志模型
backend/app/service/ApprovalService.php       # 修改 - 添加消息更新逻辑
backend/app/service/FeishuNotificationService.php  # 修改 - 添加日志记录
backend/app/controller/DebugController.php    # 新建 - 调试接口
backend/app/service/BusinessTripService.php  # 修改 - 添加node_id参数
backend/config/route.php                       # 修改 - 添加调试路由
```

### 数据库变更
```
新建表：
- feishu_message        # 消息映射表
- feishu_message_log     # 消息日志表
```

---

## 🚀 部署步骤

### Step 1: 备份数据库
```bash
ssh root@45.153.130.80

# 备份数据库
docker exec 1Panel-mysql-XyxS mysqldump -uxserver -pNsNBSQm4b2b7SzhR xserver > backup_$(date +%Y%m%d_%H%M%S).sql
```

### Step 2: 创建数据库表
```bash
# 创建 feishu_message_log 表
docker exec 1Panel-mysql-XyxS mysql -uxserver -pNsNBSQm4b2b7SzhR xserver << 'EOF'
CREATE TABLE IF NOT EXISTS feishu_message_log (
    id bigint unsigned NOT NULL AUTO_INCREMENT,
    action varchar(20) NOT NULL COMMENT '操作类型：send=发送, update=更新, update_card=更新卡片',
    order_id bigint unsigned NOT NULL COMMENT '审批订单ID',
    node_id bigint unsigned DEFAULT NULL COMMENT '审批节点ID',
    user_id bigint unsigned DEFAULT NULL COMMENT '用户ID',
    message_id varchar(64) DEFAULT NULL COMMENT '飞书消息ID',
    status varchar(10) NOT NULL COMMENT '状态：success=成功, failed=失败',
    request_data text DEFAULT NULL COMMENT '请求数据（JSON）',
    response_data text DEFAULT NULL COMMENT '响应数据（JSON）',
    error_message text DEFAULT NULL COMMENT '错误信息',
    created_at timestamp NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY idx_order_id (order_id),
    KEY idx_action (action),
    KEY idx_status (status),
    KEY idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='飞书消息日志表';
EOF

# 验证表创建
docker exec 1Panel-mysql-XyxS mysql -uxserver -pNsNBSQm4b2b7SzhR xserver -e "SHOW TABLES LIKE 'feishu%';"
```

### Step 3: 部署代码
```bash
# 进入项目目录
cd /opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index

# 拉取最新代码
git fetch origin
git checkout feature/debug-feishu-message
git pull origin feature/debug-feishu-message
```

### Step 4: 重启后端服务
```bash
# 重启后端容器
docker restart x-server-backend

# 检查服务状态
docker logs x-server-backend --tail 50
```

### Step 5: 验证部署
```bash
# 检查PHP报错
docker logs x-server-backend 2>&1 | grep -i error

# 测试调试接口
curl "http://localhost:8787/debug/message-logs?debug=1&limit=10"
```

---

## 🧪 调试测试计划

### 测试场景1：会签（and_approve）

**配置：**
```sql
-- 确认节点类型为会签
UPDATE approval_node SET type='and_approve' WHERE id=7;
```

**测试步骤：**
1. 选择3个审批人提交申请
2. 第一个审批人通过 → 检查状态仍为 pending
3. 第二个审批人通过 → 检查状态仍为 pending
4. 第三个审批人通过 → 检查状态变为 approved
5. 检查消息日志，验证所有操作都被记录

**验证点：**
- [ ] 每次审批后状态正确更新
- [ ] 审批记录正确保存
- [ ] 消息日志有记录
- [ ] 会签完成后通知申请人

---

### 测试场景2：或签（or_approve）

**配置：**
```sql
-- 修改节点类型为或签
UPDATE approval_node SET type='or_approve' WHERE id=7;
```

**测试步骤：**
1. 选择3个审批人提交申请
2. 第一个审批人通过 → 状态变为 approved
3. 检查其他审批人的消息卡片是否更新

**验证点：**
- [ ] 一人通过后立即完成流程
- [ ] 消息卡片更新被调用
- [ ] 其他审批人的消息移除按钮
- [ ] 消息日志记录更新操作

---

### 测试场景3：单人审批（approver）

**配置：**
```sql
-- 修改节点类型为单人审批
UPDATE approval_node SET type='approver' WHERE id=7;
```

**测试步骤：**
1. 选择多个审批人提交申请
2. 第一个审批人通过 → 状态变为 approved
3. 检查消息更新

**验证点：**
- [ ] 一人通过后完成流程
- [ ] 消息卡片正确更新
- [ ] 其他人无法重复操作

---

## 🔍 问题排查

### 查看消息日志
```bash
# 查看最近50条日志
docker exec 1Panel-mysql-XyxS mysql -uxserver -pNsNBSQm4b2b7SzhR xserver -e "
SELECT id, action, order_id, user_id, message_id, status,
       created_at
FROM feishu_message_log
ORDER BY created_at DESC
LIMIT 50;
"

# 查看失败的日志
docker exec 1Panel-mysql-XyxS mysql -uxserver -pNsNBSQm4b2b7SzhR xserver -e "
SELECT * FROM feishu_message_log
WHERE status = 'failed'
ORDER BY created_at DESC
LIMIT 10\G
"
```

### 查看消息映射
```bash
# 查看某个订单的消息映射
docker exec 1Panel-mysql-XyxS mysql -uxserver -pNsNBSQm4b2b7SzhR xserver -e "
SELECT * FROM feishu_message
WHERE order_id = <ORDER_ID>;
"
```

### 查看后端日志
```bash
# 实时日志
docker logs x-server-backend -f --tail 100

# 查看特定关键词
docker logs x-server-backend 2>&1 | grep -i "飞书\|审批\|消息"
```

---

## 📊 测试记录模板

### 审批测试记录
| 订单ID | 申请人 | 审批人 | 节点类型 | 操作 | 预期结果 | 实际结果 | 状态 |
|--------|--------|--------|----------|------|----------|----------|------|
|        |        |        |          |      |          |          |      |

### 消息测试记录
| 订单ID | 操作 | message_id | 状态 | 预期行为 | 实际行为 | 状态 |
|--------|------|------------|------|----------|----------|------|
|        |      |------------|------|----------|          |      |

---

## 🔄 回滚方案

如果出现问题需要回滚：
```bash
# 回滚代码
git checkout master
git pull origin master
docker restart x-server-backend

# 恢复数据库（如果需要）
docker exec -i 1Panel-mysql-XyxS mysql -uxserver -pNsNBSQm4b2b7SzhR xserver < backup_xxx.sql
```

---

**维护人**: 开发团队
**最后更新**: 2026-02-28