From 32719406a3a96adca1649fea1df1e4ae78724149 Mon Sep 17 00:00:00 2001 From: root Date: Sat, 28 Feb 2026 23:04:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E7=BA=BF=E4=B8=8A?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E5=92=8C=E8=B0=83=E8=AF=95=E6=AD=A5=E9=AA=A4?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/DEPLOYMENT_STEPS.md | 238 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 docs/DEPLOYMENT_STEPS.md diff --git a/docs/DEPLOYMENT_STEPS.md b/docs/DEPLOYMENT_STEPS.md new file mode 100644 index 0000000..6102bfd --- /dev/null +++ b/docs/DEPLOYMENT_STEPS.md @@ -0,0 +1,238 @@ +# 线上部署和调试步骤 + +**版本**: 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 = ; +" +``` + +### 查看后端日志 +```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