# 微服务更新工单流程

**工单类型代码**: `microservice_update`  
**来源模块**: deliver-update  
**编制日期**: 2026-01-08

---

## 1. 业务场景

普通用户在构建详情页面发起微服务更新请求，经过超级管理员审批后执行更新操作，并监控微服务运行状态。

### 1.1 业务规则

| 规则项 | 说明 |
|-------|------|
| 发起人 | 普通用户 |
| 审批人 | 超级管理员 |
| 执行人 | 超级管理员或委派人 |
| 支持定时执行 | 是 |
| 支持委派 | 是（超管可委派给其他人执行） |
| 自动回滚 | 是（更新失败时自动回滚） |

### 1.2 相关模块

| 模块 | 职责 |
|-----|------|
| rmdc-jenkins-branch-dac | 提供构建物信息 |
| rmdc-exchange-hub | MQTT消息中继 |
| rmdc-watchdog | K8S操作执行、状态监控 |

---

## 2. 状态机

### 2.1 状态定义

| 状态代码 | 状态名称 | 说明 | 是否扩展状态 |
|---------|---------|------|------------|
| `created` | 已创建 | 用户发起更新请求 | 否 |
| `pending_review` | 待审核 | 等待超级管理员审核 | 否 |
| `approved` | 已批准 | 审核通过，等待执行 | 否 |
| `returned` | 已打回 | 审核打回，需修改 | 否 |
| `rejected` | 已拒绝 | 审核拒绝，流程终止 | 否 |
| `executing` | 执行中 | 微服务更新正在执行 | 是 |
| `monitoring` | 监控中 | 更新完成，监控运行状态 | 是 |
| `rollbacked` | 已回滚 | 更新失败，已自动回滚 | 是 |
| `closed` | 已关闭 | 工单生命周期结束 | 否 |
| `revoked` | 已撤销 | 用户撤销更新请求 | 否 |

### 2.2 状态机图

```mermaid
stateDiagram-v2
    [*] --> created: 发起更新请求
    
    created --> pending_review: 提交审核
    created --> revoked: 用户撤销
    
    pending_review --> approved: 审批通过
    pending_review --> returned: 审批打回
    pending_review --> rejected: 审批拒绝
    pending_review --> revoked: 用户撤销
    
    returned --> pending_review: 修改后重新提交
    returned --> revoked: 用户撤销
    
    approved --> executing: 开始执行
    approved --> approved: 等待定时执行
    
    executing --> monitoring: 更新成功
    executing --> executing: 执行重试
    executing --> rollbacked: 更新失败回滚
    
    monitoring --> closed: 运行正常
    monitoring --> rollbacked: 运行异常回滚
    
    rollbacked --> closed: 记录失败信息
    rejected --> closed: 关闭工单
    revoked --> closed: 关闭工单
    
    closed --> [*]
    
    note right of executing: 通过rmdc-watchdog执行
    note right of monitoring: 监控微服务健康状态
    note right of rollbacked: 自动回滚到更新前版本
```

---

## 3. 流程图

```mermaid
flowchart TD
    Start([开始]) --> SelectBuild[用户选择构建物]
    SelectBuild --> JumpToUpdate[跳转微服务更新页面]
    
    JumpToUpdate --> ThreeColumns[三栏布局页面]
    ThreeColumns --> LeftColumn[左栏：构建物信息]
    ThreeColumns --> MiddleColumn[中栏：更新表单]
    ThreeColumns --> RightColumn[右栏：发起按钮]
    
    MiddleColumn --> FillForm[填写更新信息]
    FillForm --> SelectProject[选择目标项目]
    SelectProject --> SelectService[选择目标微服务]
    SelectService --> SetSchedule[设置更新时间]
    
    SetSchedule --> SubmitRequest[提交更新请求]
    SubmitRequest --> CreateWorkflow[创建更新工单]
    
    CreateWorkflow --> PendingReview{待审核}
    
    PendingReview -->|审批通过| CheckSchedule{是否定时执行?}
    PendingReview -->|审批打回| Return[打回修改]
    PendingReview -->|审批拒绝| Reject[拒绝请求]
    PendingReview -->|用户撤销| Revoke[撤销请求]
    
    Return --> ModifyRequest[修改更新信息]
    ModifyRequest --> SubmitRequest
    
    CheckSchedule -->|立即执行| StartExecute[开始执行更新]
    CheckSchedule -->|定时执行| WaitSchedule[等待定时触发]
    WaitSchedule --> StartExecute
    
    StartExecute --> Executing{执行更新}
    
    Executing -->|成功| Monitoring[监控运行状态]
    Executing -->|失败| RetryCheck{重试?}
    
    RetryCheck -->|是| StartExecute
    RetryCheck -->|否| Rollback[自动回滚]
    
    Monitoring --> HealthCheck{健康检查}
    
    HealthCheck -->|正常| CloseSuccess[工单关闭-成功]
    HealthCheck -->|异常| Rollback
    
    Rollback --> RecordFailure[记录失败信息]
    RecordFailure --> CloseFailure[工单关闭-回滚]
    
    Reject --> CloseRejected[工单关闭]
    Revoke --> CloseRevoked[工单关闭]
    
    CloseSuccess --> End([结束])
    CloseFailure --> End
    CloseRejected --> End
    CloseRevoked --> End
```

---

## 4. 时序图

```mermaid
sequenceDiagram
    autonumber
    
    participant User as 普通用户
    participant Frontend as 前端
    participant Jenkins as rmdc-jenkins
    participant Workflow as rmdc-work-procedure
    participant SuperAdmin as 超级管理员
    participant ExHub as rmdc-exchange-hub
    participant Watchdog as rmdc-watchdog
    participant Notice as 通知中心
    
    %% 发起更新请求
    User->>Frontend: 查看构建详情
    Frontend->>Jenkins: POST /api/jenkins/build/detail
    Jenkins-->>Frontend: 返回构建物信息
    User->>Frontend: 点击微服务更新
    Frontend->>Frontend: 跳转更新页面(携带构建信息)
    
    User->>Frontend: 填写更新表单
    Note over Frontend: 选择项目、微服务、更新时间
    User->>Frontend: 点击发起更新
    Frontend->>Workflow: POST /api/workflow/create
    Note over Workflow: 创建microservice_update工单<br/>保存build_id, target_version
    Workflow->>Workflow: 设置status=pending_review
    Workflow->>Notice: 推送通知
    Notice-->>SuperAdmin: 微服务更新审批通知
    
    %% 审批阶段
    alt 审批通过
        SuperAdmin->>Frontend: 审批通过
        Frontend->>Workflow: POST /api/workflow/transition
        Note over Workflow: event=approve
        Workflow->>Workflow: 设置status=approved
        
        alt 立即执行
            Workflow->>Workflow: 设置status=executing
            Workflow->>ExHub: 发送更新指令
            ExHub->>Watchdog: MQTT下发更新命令
            
            %% 执行更新
            Watchdog->>Watchdog: 执行K8S滚动更新
            
            alt 更新成功
                Watchdog-->>ExHub: 上报更新成功
                ExHub->>Workflow: POST /api/workflow/callback
                Workflow->>Workflow: 设置status=monitoring
                
                %% 健康监控
                loop 健康检查(5分钟)
                    Watchdog->>Watchdog: 检查Pod状态
                end
                
                alt 运行正常
                    Watchdog-->>ExHub: 上报运行正常
                    ExHub->>Workflow: POST /api/workflow/callback
                    Workflow->>Workflow: 设置status=closed
                    Workflow->>Notice: 推送通知
                    Notice-->>User: 微服务更新成功
                else 运行异常
                    Watchdog->>Watchdog: 自动回滚
                    Watchdog-->>ExHub: 上报回滚结果
                    ExHub->>Workflow: POST /api/workflow/callback
                    Note over Workflow: 记录rollback_info
                    Workflow->>Workflow: 设置status=rollbacked
                    Workflow->>Notice: 推送通知
                    Notice-->>User: 微服务更新回滚
                end
            else 更新失败
                Watchdog->>Watchdog: 自动回滚
                Watchdog-->>ExHub: 上报失败+回滚
                ExHub->>Workflow: POST /api/workflow/callback
                Workflow->>Workflow: 设置status=rollbacked
            end
            
        else 定时执行
            Note over Workflow: 等待scheduled_at时间
            Workflow->>Workflow: 定时触发执行
        end
    
    else 审批打回
        SuperAdmin->>Frontend: 打回修改
        Frontend->>Workflow: POST /api/workflow/transition
        Note over Workflow: event=return
        Workflow->>Workflow: 设置status=returned
        Workflow->>Notice: 推送通知
        Notice-->>User: 更新请求被打回
    
    else 审批拒绝
        SuperAdmin->>Frontend: 拒绝请求
        Frontend->>Workflow: POST /api/workflow/transition
        Note over Workflow: event=reject
        Workflow->>Workflow: 设置status=rejected
    end
```

---

## 5. 工单步骤定义

| 步骤序号 | 步骤名称 | 步骤类型 | 处理人 | 操作说明 |
|---------|---------|---------|-------|---------|
| 1 | 提交更新请求 | `submit` | 普通用户 | 填写更新信息并提交 |
| 2 | 审核更新请求 | `approve` | 超级管理员 | 审批通过/打回/拒绝 |
| 3 | 执行更新 | `execute` | 超级管理员/委派人 | 执行微服务滚动更新 |
| 4 | 监控运行状态 | `monitor` | 系统自动 | 监控微服务健康状态 |

---

## 6. 业务扩展字段

存储于 `microservice_update_ext` 表：

| 字段 | 类型 | 说明 |
|-----|------|------|
| `project_id` | VARCHAR(64) | 目标项目ID |
| `namespace` | VARCHAR(64) | K8S命名空间 |
| `service_name` | VARCHAR(128) | 微服务名称 |
| `build_id` | VARCHAR(128) | 构建物ID |
| `current_version` | VARCHAR(64) | 当前版本 |
| `target_version` | VARCHAR(64) | 目标版本 |
| `scheduled_at` | DATETIME | 计划执行时间 |
| `execute_result` | VARCHAR(32) | 执行结果：success/failed/rollbacked |
| `rollback_info` | JSON | 回滚信息 |

### 6.1 rollback_info 示例

```json
{
  "rollback_reason": "Pod健康检查失败",
  "rollback_time": "2026-01-08T15:30:00Z",
  "rollback_version": "v3.1.5",
  "error_details": {
    "pod_name": "service-abc-7d8f9c6b5d-xyz",
    "error_message": "Readiness probe failed: connection refused",
    "failed_checks": 3
  }
}
```

---

## 7. 更新页面布局

```
┌─────────────────────────────────────────────────────────────────┐
│                         微服务更新                               │
├─────────────────┬─────────────────────────┬────────────────────┤
│   构建物信息     │      更新表单            │    操作区          │
│                 │                         │                    │
│ 组织: acme      │ 目标项目: [下拉选择]     │                    │
│ 仓库: service   │ 目标微服务: [下拉选择]   │   [发起更新]       │
│ 分支: main      │ 更新时间: [日期选择]     │                    │
│ 构建号: #123    │   ○ 立即执行             │   [取消]           │
│ 版本: v3.2.0    │   ○ 定时执行             │                    │
│                 │ 备注: [文本框]           │                    │
│                 │                         │                    │
└─────────────────┴─────────────────────────┴────────────────────┘
```
