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: 备份数据库

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: 创建数据库表

# 创建 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: 部署代码

# 进入项目目录
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: 重启后端服务

# 重启后端容器
docker restart x-server-backend

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

Step 5: 验证部署

# 检查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）

配置：

-- 确认节点类型为会签
UPDATE approval_node SET type='and_approve' WHERE id=7;

测试步骤：

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

验证点：

• 每次审批后状态正确更新
• 审批记录正确保存
• 消息日志有记录
• 会签完成后通知申请人

---

测试场景2：或签（or_approve）

配置：

-- 修改节点类型为或签
UPDATE approval_node SET type='or_approve' WHERE id=7;

测试步骤：

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

验证点：

• 一人通过后立即完成流程
• 消息卡片更新被调用
• 其他审批人的消息移除按钮
• 消息日志记录更新操作

---

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

配置：

-- 修改节点类型为单人审批
UPDATE approval_node SET type='approver' WHERE id=7;

测试步骤：

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

验证点：

• 一人通过后完成流程
• 消息卡片正确更新
• 其他人无法重复操作

---

🔍 问题排查

查看消息日志

# 查看最近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
"

查看消息映射

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

查看后端日志

# 实时日志
docker logs x-server-backend -f --tail 100

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

---

📊 测试记录模板

审批测试记录

订单ID	申请人	审批人	节点类型	操作	预期结果	实际结果	状态

消息测试记录

订单ID	操作	message_id	状态	预期行为	实际行为	状态
		------------	------	----------

---

🔄 回滚方案

如果出现问题需要回滚：

# 回滚代码
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